{"id":17160496,"url":"https://github.com/mattpolzin/jsonapi","last_synced_at":"2025-04-10T19:03:20.570Z","repository":{"id":41432474,"uuid":"157320571","full_name":"mattpolzin/JSONAPI","owner":"mattpolzin","description":"Swift Codable JSON:API framework","archived":false,"fork":false,"pushed_at":"2024-04-30T16:29:18.000Z","size":846,"stargazers_count":75,"open_issues_count":8,"forks_count":21,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-23T23:44:42.312Z","etag":null,"topics":["generic","json-api","safety","swift","swift-library"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mattpolzin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-11-13T04:32:05.000Z","updated_at":"2024-09-12T18:17:08.000Z","dependencies_parsed_at":"2024-03-27T20:24:10.306Z","dependency_job_id":"013aa225-3fe2-4e68-a7e7-abca41dca6c9","html_url":"https://github.com/mattpolzin/JSONAPI","commit_stats":{"total_commits":481,"total_committers":7,"mean_commits":68.71428571428571,"dds":"0.018711018711018657","last_synced_commit":"c5d1e71c9769eb83e9cfc02c45d0359ace3670d7"},"previous_names":[],"tags_count":85,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattpolzin%2FJSONAPI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattpolzin%2FJSONAPI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattpolzin%2FJSONAPI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattpolzin%2FJSONAPI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mattpolzin","download_url":"https://codeload.github.com/mattpolzin/JSONAPI/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245314068,"owners_count":20595199,"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":["generic","json-api","safety","swift","swift-library"],"created_at":"2024-10-14T22:25:03.955Z","updated_at":"2025-03-27T22:33:10.247Z","avatar_url":"https://github.com/mattpolzin.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JSONAPI\n[![MIT license](http://img.shields.io/badge/license-MIT-lightgrey.svg)](http://opensource.org/licenses/MIT) [![Swift 5.2+](http://img.shields.io/badge/Swift-5.2/5.3/5.4-blue.svg)](https://swift.org) [![Build Status](https://app.bitrise.io/app/c8295b9589aa401e/status.svg?token=vzcyqWD5bQ4xqQfZsaVzNw\u0026branch=main)](https://app.bitrise.io/app/c8295b9589aa401e)\n\nA Swift package for encoding to- and decoding from **JSON API** compliant requests and responses.\n\nSee the JSON API Spec here: https://jsonapi.org/format/\n\n## Quick Start\n\n:warning: The following Google Colab examples have correct code, but from time to time the Google Colab Swift compiler may be buggy and claim it cannot build the JSONAPI library.\n\n### Clientside\n- [Basic Example](https://colab.research.google.com/drive/1IS7lRSBGoiW02Vd1nN_rfdDbZvTDj6Te)\n- [Compound Example](https://colab.research.google.com/drive/1BdF0Kc7l2ixDfBZEL16FY6palweDszQU)\n- [Metadata Example](https://colab.research.google.com/drive/10dEESwiE9I3YoyfzVeOVwOKUTEgLT3qr)\n- [Custom Errors Example](https://colab.research.google.com/drive/1TIv6STzlHrkTf_-9Eu8sv8NoaxhZcFZH)\n- [PATCH Example](https://colab.research.google.com/drive/16KY-0BoLQKiSUh9G7nYmHzB8b2vhXA2U)\n- [Resource Storage Example](https://colab.research.google.com/drive/196eCnBlf2xz8pT4lW--ur6eWSVAjpF6b?usp=sharing) (using [JSONAPI-ResourceStorage](#jsonapi-resourcestorage))\n\n### Serverside\n- [GET Example](https://colab.research.google.com/drive/1krbhzSfz8mwkBTQQnKUZJLEtYsJKSfYX)\n- [POST Example](https://colab.research.google.com/drive/1z3n70LwRY7vLIgbsMghvnfHA67QiuqpQ)\n\n### Client+Server\nThis library works well when used by both the server responsible for serialization and the client responsible for deserialization. Check out the [example](./documentation/client-server-example.md).\n\n## Table of Contents\n- JSONAPI\n\t- [Primary Goals](#primary-goals)\n\t- [Dev Environment](#dev-environment)\n\t\t- [Prerequisites](#prerequisites)\n\t\t- [Swift Package Manager](#swift-package-manager)\n\t\t- [Xcode project](#xcode-project)\n\t\t- [CocoaPods](#cocoapods)\n\t\t- [Running the Playground](#running-the-playground)\n\t- [Project Status](./documentation/project-status.md)\n\t- [Server \u0026 Client Example](./documentation/client-server-example.md)\n\t- [Usage](./documentation/usage.md)\n- [JSONAPI+Testing](#jsonapitesting)\n\t- [Literal Expressibility](#literal-expressibility)\n\t- [Resource Object `check()`](#resource-object-check)\n\t- [Comparisons](#comparisons)\n- [JSONAPI-Arbitrary](#jsonapi-arbitrary)\n- [JSONAPI-OpenAPI](#jsonapi-openapi)\n- [JSONAPI-ResourceStorage](#jsonapi-resourcestorage)\n\n## Primary Goals\n\nThe primary goals of this framework are:\n1. Allow creation of Swift types that are easy to use in code but also can be encoded to- or decoded from **JSON API v1.0 Spec** compliant payloads without lots of boilerplate code.\n2. Leverage `Codable` to avoid additional outside dependencies and get operability with non-JSON encoders/decoders for free.\n3. Do not sacrifice type safety.\n4. Be platform agnostic so that Swift code can be written once and used by both the client and the server.\n5. Provide _human readable_ error output. The errors thrown when decoding an API response and the results of the `JSONAPITesting` framework's `compare(to:)` functions all have digestible human readable descriptions (just use `String(describing:)`).\n\n### Caveat\nThe big caveat is that, although the aim is to support the JSON API spec, this framework ends up being _naturally_ opinionated about certain things that the API Spec does not specify. These caveats are largely a side effect of attempting to write the library in a \"Swifty\" way.\n\nIf you find something wrong with this library and it isn't already mentioned under **Project Status**, let me know! I want to keep working towards a library implementation that is useful in any application.\n\n## Dev Environment\n### Prerequisites\n1. Swift 5.2+\n2. Swift Package Manager, Xcode 11+, or Cocoapods\n\n### Swift Package Manager\nJust include the following in your package's dependencies and add `JSONAPI` to the dependencies for any of your targets.\n```swift\n.package(url: \"https://github.com/mattpolzin/JSONAPI.git\", from: \"5.1.0\")\n```\n\n### Xcode project\nWith Xcode 11+, you can open the folder containing this repository. There is no need for an Xcode project, but you can generate one with `swift package generate-xcodeproj`.\n\n### CocoaPods\nTo use this framework in your project via Cocoapods, add the following dependencies to your Podfile.\n```ruby\npod 'Poly', :git =\u003e 'https://github.com/mattpolzin/Poly.git'\npod 'MP-JSONAPI', :git =\u003e 'https://github.com/mattpolzin/JSONAPI.git'\n```\n\n### Carthage\nThis library does not support the Carthage package manager. This is intentional to avoid an additional dependency on Xcode and the Xcode's project files as their format changes throughout versions (in addition to the complexity of maintaining different shared schemes for each supported operating system). \n\nThe difference between supporting and not supporting Carthage is the difference between maintaining an Xcode project with at least one shared build scheme; I encourage those that need Carthage support to fork this repository and add support to their fork by committing an Xcode project (you can generate one as described in the [Xcode project](#xcode-project) section above). Once an Xcode project is generated, you need to mark at least one scheme as [shared](https://github.com/Carthage/Carthage#share-your-xcode-schemes).\n\n### Running the Playground\nTo run the included Playground files, create an Xcode project using Swift Package Manager, then create an Xcode Workspace in the root of the repository and add both the generated Xcode project and the playground to the Workspace.\n\nNote that Playground support for importing non-system Frameworks is still a bit touchy as of Swift 4.2. Sometimes building, cleaning and building, or commenting out and then uncommenting import statements (especially in the` Entities.swift` Playground Source file) can get things working for me when I am getting an error about `JSONAPI` not being found.\n\n## Deeper Dive\n- [Project Status](./documentation/project-status.md)\n- [Server \u0026 Client Example](./documentation/client-server-example.md)\n- [Usage Documentation](./documentation/usage.md)\n\n# JSONAPI+Testing\nThe `JSONAPI` framework is packaged with a test library to help you test your `JSONAPI` integration. The test library is called `JSONAPITesting`. You can see `JSONAPITesting` in action in the Playground included with the `JSONAPI` repository.\n\n## Literal Expressibility\nLiteral expressibility for `Attribute`, `ToOneRelationship`, and `Id` are provided so that you can easily write test `ResourceObject` values into your unit tests.\n\nFor example, you could create a mock `Author` (from the above example) as follows\n```swift\nlet author = Author(\n\tid: \"1234\", // You can just use a String directly as an Id\n\tattributes: .init(name: \"Janice Bluff\"), // The name Attribute does not need to be initialized, you just use a String directly.\n\trelationships: .none,\n\tmeta: .none,\n\tlinks: .none\n)\n```\n\n## Resource Object `check()`\nThe `ResourceObject` gets a `check()` function that can be used to catch problems with your `JSONAPI` structures that are not caught by Swift's type system.\n\nTo catch malformed `JSONAPI.Attributes` and `JSONAPI.Relationships`, just call `check()` in your unit test functions:\n```swift\nfunc test_initAuthor() {\n\tlet author = Author(...)\n\tAuthor.check(author)\n}\n```\n\n## Comparisons\nYou can compare `Documents`, `ResourceObjects`, `Attributes`, etc. and get human-readable output using the `compare(to:)` methods included with `JSONAPITesting`.\n\n```swift\nfunc test_articleResponse() {\n\tlet endToEndAPITestResponse: SingleArticleDocumentWithIncludes = ...\n\n\tlet expectedResponse: SingleArticleDocumentWithIncludes = ...\n\n\tlet comparison = endToEndAPITestResponse.compare(to: expectedResponse)\n\n\tXCTAssert(comparison.isSame, String(describing: comparison))\n}\n```\n\n# JSONAPI-Arbitrary\nThe `JSONAPI-Arbitrary` library provides `SwiftCheck` `Arbitrary` conformance for many of the `JSONAPI` types.\n\nSee https://github.com/mattpolzin/JSONAPI-Arbitrary for more information.\n\n# JSONAPI-OpenAPI\nThe `JSONAPI-OpenAPI` library generates OpenAPI compliant JSON Schema for models built with the `JSONAPI` library. If your Swift code is your preferred source of truth for API information, this is an easy way to document the response schemas of your API.\n\n`JSONAPI-OpenAPI` also has experimental support for generating `JSONAPI` Swift code from Open API documentation (this currently lives on the `feature/gen-swift` branch).\n\nSee https://github.com/mattpolzin/JSONAPI-OpenAPI for more information.\n\n# JSONAPI-ResourceStorage\nThe `JSONAPI-ResourceStorage` package has two _very_ early stage modules supporting storage and retrieval of `JSONAPI.ResourceObjects`. Please consider these modules to be more of examples of two directions you could head in than anything else.\n\nhttps://github.com/mattpolzin/JSONAPI-ResourceStorage\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattpolzin%2Fjsonapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmattpolzin%2Fjsonapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattpolzin%2Fjsonapi/lists"}