{"id":19712567,"url":"https://github.com/evgenyneu/jsonswiftson","last_synced_at":"2025-04-29T18:30:56.272Z","repository":{"id":31788018,"uuid":"35354463","full_name":"evgenyneu/JsonSwiftson","owner":"evgenyneu","description":"A JSON parser with concise API written in Swift.","archived":false,"fork":false,"pushed_at":"2017-04-07T23:35:52.000Z","size":521,"stargazers_count":14,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-18T10:24:29.375Z","etag":null,"topics":["json","json-parser","swift"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"zfpx/201801JS","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/evgenyneu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-05-10T02:49:09.000Z","updated_at":"2018-08-13T15:04:54.000Z","dependencies_parsed_at":"2022-08-20T21:20:23.848Z","dependency_job_id":null,"html_url":"https://github.com/evgenyneu/JsonSwiftson","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evgenyneu%2FJsonSwiftson","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evgenyneu%2FJsonSwiftson/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evgenyneu%2FJsonSwiftson/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evgenyneu%2FJsonSwiftson/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/evgenyneu","download_url":"https://codeload.github.com/evgenyneu/JsonSwiftson/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251559775,"owners_count":21609072,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json","json-parser","swift"],"created_at":"2024-11-11T22:17:38.953Z","updated_at":"2025-04-29T18:30:55.726Z","avatar_url":"https://github.com/evgenyneu.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# A JSON parser with concise API written in Swift\n\n[![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)\n[![CocoaPods Version](https://img.shields.io/cocoapods/v/JsonSwiftson.svg?style=flat)](http://cocoadocs.org/docsets/JsonSwiftson)\n[![License](https://img.shields.io/cocoapods/l/JsonSwiftson.svg?style=flat)](http://cocoadocs.org/docsets/JsonSwiftson)\n[![Platform](https://img.shields.io/cocoapods/p/JsonSwiftson.svg?style=flat)](http://cocoadocs.org/docsets/JsonSwiftson)\n\n\u003cimg src='https://raw.githubusercontent.com/evgenyneu/JsonSwiftson/master/Graphics/GithubLogo/json_swiftson_parser.png' width='200' alt='JsonSwiftson JSON parser for Swift'\u003e\n\n* Maps JSON attributes to different Swift types with just two methods: `map` and `mapArrayOfObjects`.\n* The library can be used on any platform that runs Swift.\n* Supports casting to optional types.\n* Indicates if the mapping was successful.\n* Can be used in Swift apps for Apple devices and in open source Swift programs on other platforms.\n\n### Example\n\nThe following is an example of mapping a JSON text into a Swift `Person` structure.\n\n```Swift\nstruct Person {\n  let name: String\n  let age: Int\n}\n\nlet mapper = JsonSwiftson(json: \"{ \\\"name\\\": \\\"Peter\\\", \\\"age\\\": 41 }\")\n\nlet person = Person(\n  name: mapper[\"name\"].map() ?? \"\",\n  age: mapper[\"age\"].map() ?? 0\n)\n\nif !mapper.ok { /* report error */ }\n```\n\n## Setup (Swift 3.0)\n\nThere are four ways you can add JsonSwiftson into your project.\n\n#### Add the source file (iOS 7+)\n\nSimply add [JsonSwiftson.swift](https://github.com/evgenyneu/JsonSwiftson/blob/master/JsonSwiftson/JsonSwiftson.swift) file to your Xcode project.\n\n#### Setup with Carthage (iOS 8+)\n\nAlternatively, add `github \"evgenyneu/JsonSwiftson\" ~\u003e 4.0` to your Cartfile and run `carthage update`.\n\n#### Setup with CocoaPods (iOS 8+)\n\nIf you are using CocoaPods add this text to your Podfile and run `pod install`.\n\n    use_frameworks!\n    target 'Your target name'\n    pod 'JsonSwiftson', git: 'https://github.com/evgenyneu/JsonSwiftson.git', tag: '4.0.0'\n\n\n#### Setup with Swift Package Manager\n\nAdd the following text to your Package.swift file and run `swift build`.\n\n```Swift\nimport PackageDescription\n\nlet package = Package(\n    name: \"YourPackageName\",\n    targets: [],\n    dependencies: [\n        .Package(url: \"https://github.com/evgenyneu/JsonSwiftson.git\",\n                 versions: Version(3,0,0)..\u003cVersion(4,0,0))\n    ]\n)\n```\n\n\n### Legacy Swift versions\n\nSetup a [previous version](https://github.com/evgenyneu/JsonSwiftson/wiki/Legacy-Swift-versions) of the library if you use an older version of Swift.\n\n\n\n## Usage\n\n1) Add `import JsonSwiftson` to your source code if you used Carthage or CocoaPods setup.\n\n2) Create an instance of `JsonSwiftson` class and supply a JSON text for parsing.\n\n```Swift\nlet mapper = JsonSwiftson(json: \"{ \\\"person\\\": { \\\"name\\\": \\\"Michael\\\" }}\")\n```\n\n3) Supply the name of JSON attribute you want to get and call the `map` method. The type of the JSON value is inferred from the context.\n\n```Swift\nlet name: String? = mapper[\"person\"][\"name\"].map()\n```\n\nThe example above mapped JSON to an optional String type. One can map to a non-optional by using the `??` operator and supplying a default value.\n\n```Swift\nlet name: String = mapper[\"person\"][\"name\"].map() ?? \"Default name\"\n```\n\n4) Finally, check `ok` property to see if mapping was successful.\n\n```Swift\nif !mapper.ok { /* report error */ }\n```\n\nThe `ok` property will return `false` if JSON parsing failed or the attribute with the given name was missing. You can allow the attribute to be missing by supplying the `optional: true` argument to the `map` method.\n\n```JSON\nlet name: String? = mapper[\"person\"][\"name\"].map(optional: true)\n```\n\n### Map to simple Swift types\n\nUse the `map` method to parse JSON to types like strings, numbers and booleans.\n\n\n```Swift\n// String\nlet stringMapper = JsonSwiftson(json: \"\\\"Hello World\\\"\")\nlet string: String? = stringMapper.map()\n\n// Integer\nlet intMapper = JsonSwiftson(json: \"123\")\nlet int: Int? = intMapper.map()\n\n// Double\nlet doubleMapper = JsonSwiftson(json: \"123.456\")\nlet double: Double? = doubleMapper.map()\n\n// Boolean\nlet boolMapper = JsonSwiftson(json: \"true\")\nlet bool: Bool? = boolMapper.map()\n```\n\n### Map property by name\n\nUse square brackets to reach JSON properties by name: `mapper[\"name\"]`.\n\n```Swift\nlet mapper = JsonSwiftson(json: \"{ \\\"name\\\": \\\"Michael\\\" }\")\nlet name: String? = mapper[\"name\"].map()\n```\n\nOne can use square brackets more than once to reach deeper JSON properties: `mapper[\"person\"][\"name\"]`.\n\n```Swift\nlet mapper = JsonSwiftson(json: \"{ \\\"person\\\": { \\\"name\\\": \\\"Michael\\\" }}\")\nlet name: String? = mapper[\"person\"][\"name\"].map()\n```\n\n### Map arrays of simple values\n\nJsonSwiftson will automatically map to the arrays of strings, numbers and booleans.\n\n```Swift\n// String\nlet stringMapper = JsonSwiftson(json: \"[\\\"One\\\", \\\"Two\\\"]\")\nlet string: [String]? = stringMapper.map()\n\n// Integer\nlet intMapper = JsonSwiftson(json: \"[1, 2]\")\nlet int: [Int]? = intMapper.map()\n\n// Double\nlet doubleMapper = JsonSwiftson(json: \"[1.1, 2.2]\")\nlet double: [Double]? = doubleMapper.map()\n\n// Boolean\nlet boolMapper = JsonSwiftson(json: \"[true, false]\")\nlet bool: [Bool]? = boolMapper.map()\n```\n\n### Map an array of objects\n\nUse `mapArrayOfObjects` with a closure to map array of objects.\n\n```Swift\nstruct Person {\n  let name: String\n  let age: Int\n}\n\nlet mapper = JsonSwiftson(json:\n  \"[ \" +\n    \"{ \\\"name\\\": \\\"Peter\\\", \\\"age\\\": 41 },\" +\n    \"{ \\\"name\\\": \\\"Ted\\\", \\\"age\\\": 51 }\" +\n  \"]\")\n\nlet people: [Person]? = mapper.mapArrayOfObjects { j in\n  Person(\n    name: j[\"name\"].map() ?? \"\",\n    age: j[\"age\"].map() ?? 0\n  )\n}\n```\n\n**Tip**: Use `map` method instead of `mapArrayOfObjects` for mapping arrays of simple values like strings, numbers and booleans.\n\n### Mapping to Swift structures\n\n```Swift\nstruct Person {\n  let name: String\n  let age: Int\n}\n\nlet mapper = JsonSwiftson(json: \"{ \\\"name\\\": \\\"Peter\\\", \\\"age\\\": 41 }\")\n\nlet person = Person(\n  name: mapper[\"name\"].map() ?? \"\",\n  age: mapper[\"age\"].map() ?? 0\n)\n```\n\n### Check if mapping was successful\n\nVerify the `ok` property to see if mapping was successful.\nMapping fails for incorrect JSON and type casting problems.\n\n**Note**: `map` and `mapArrayOfObjects` methods always return `nil` if mapping fails.\n\n```Swift\nlet successMapper = JsonSwiftson(json: \"\\\"Correct type\\\"\")\nlet string: String? = successMapper.map()\nif successMapper.ok { print(\"👏👏👏\") }\n\nlet failMapper = JsonSwiftson(json: \"\\\"Wrong type\\\"\")\nlet number: Int? = failMapper.map()\nif !failMapper.ok { print(\"🐞\") }\n```\n\n### Allow missing values\n\nMapping fails by default if JSON value is null or attribute is missing.\n\n**Tip:** Pass `optional: true` parameter to allow missing JSON attributes and null values.\n\n```Swift\nlet mapper = JsonSwiftson(json: \"{ }\")\nlet string: String? = mapper[\"name\"].map(optional: true)\nif mapper.ok { print(\"👏👏👏\") }\n```\n\n### Allow missing objects\n\nUse `map` method with `optional: true` parameter and a closure to allow empty objects.\n\n```\nstruct Person {\n  let name: String\n  let age: Int\n}\n\nlet mapper = JsonSwiftson(json: \"null\") // empty\n\nlet person: Person? = mapper.map(optional: true) { j in\n  Person(\n    name: j[\"name\"].map() ?? \"\",\n    age: j[\"age\"].map() ?? 0\n  )\n}\n\nif mapper.ok { print(\"👏👏👏\") }\n```\n\n### Tip: map to a non-optional type\n\nUse `??` operator after the mapper if you need to map to a non-optional type like `let number: Int`.\n\n```Swift\nlet numberMapper = JsonSwiftson(json: \"123\")\nlet number: Int = numberMapper.map() ?? 0\n\nlet arrayMapper = JsonSwiftson(json: \"[1, 2, 3]\")\nlet numbers: [Int] = arrayMapper.map() ?? []\n```\n\n### Performance benchmark\n\nThe project includes a demo app that runs performance benchmark. It maps a large JSON file containing 100 records. The process is repeated 100 times.\n\n\u003cimg src='https://raw.githubusercontent.com/evgenyneu/JsonSwiftson/master/Graphics/json_swiftson_screenshot.png' alt='Json Swiftson performance benchmark' width='320'\u003e\n\n## Alternative solutions\n\nHere is a list of excellent libraries that can help taming JSON in Swift.\n\n* [Argo](https://github.com/thoughtbot/Argo)\n* [json-swift](https://github.com/owensd/json-swift)\n* [JSONJoy-Swift](https://github.com/daltoniam/JSONJoy-Swift)\n* [ObjectMapper](https://github.com/Hearst-DD/ObjectMapper)\n* [SwiftyJSON](https://github.com/SwiftyJSON/SwiftyJSON)\n\n## License\n\nJsonSwiftson is released under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevgenyneu%2Fjsonswiftson","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevgenyneu%2Fjsonswiftson","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevgenyneu%2Fjsonswiftson/lists"}