jsonapi

jsonapi is a strict, framework-agnostic implementation of JSON:API 1.1, the official Atomic Operations extension, the official Cursor Pagination profile, and the published JSON:API recommendations.

Status

The latest published stable release is v2.0.0, with finite direct cursor admission and endpoint page limits. Read the migration notes and compatibility policy before adopting v2.

Requirements

• Go 1.27.0 or later

Installation

go get github.com/faustbrian/go-jsonapi/[email protected]

Import github.com/faustbrian/go-jsonapi/v2. Examples below describe the published v2 API.

Quickstart

document := jsonapi.Document{Data: jsonapi.ResourceData(
    jsonapi.ResourceObject{
        Type: "articles",
        ID:   "1",
        Attributes: jsonapi.Attributes{
            "title": "JSON:API in Go",
        },
    },
)}

payload, err := jsonapi.Marshal(document)
if err != nil {
    return err
}

The runnable ExampleMarshal keeps this introductory flow compiler-checked.

Decode untrusted input with Unmarshal or a configured Codec. Use request-specific validation contexts, bounded decoding, content negotiation, and query parsing as described in the quickstart.

Package Guarantees

• JSON:API 1.1 document modeling, strict decoding, validation, and stable serialization
• compound documents, relationships, errors, local identifiers, and contextual request/response validation
• sparse fieldsets, includes, sorting, pagination, filtering, and registered query families
• media-type negotiation with extensions, profiles, quality values, and wildcard candidates
• full official Atomic Operations and Cursor Pagination support
• registered extension members, profile validators, UTF-8 enforcement, and configurable resource limits

The package does not choose an HTTP router, persistence layer, filtering language, cursor encoding, authentication policy, or domain-error mapping.

Documentation

Start with the documentation index, quickstart, guide for adopting the package, and API reference. The conformance matrix, extensions and profiles, recommendations, specification decision register, and security model define the supported protocol surface. Release history is maintained in CHANGELOG.md. For help and responsible disclosure, use the support and security policies.

For ecosystem-wide selection and ownership guidance, see the versioned Golib ecosystem index and its Protocols and descriptions family.

Development

Start isolated root changes with GOWORK=off go test ./.... With the public verifier pinned in .golib.yaml, make check and make ci select bounded local verification; make check-full retains explicit full assurance. See contributor verification for focused 2s fuzzing, optional mutation and relevant protocol, ownership and release checks.

Run make interoperability to reproduce the pinned maintained-peer decision matrix without adding competitor dependencies to the public module.

Contributing

Read CONTRIBUTING.md and follow the code of conduct. Normative requirements, recommendations, extensions, profiles, and application conventions are reviewed as separate categories.

Security

Report vulnerabilities privately according to SECURITY.md. Review the security guide and threat model before processing untrusted input.

License

jsonapi is available under the MIT License. Attribution and third-party policy are recorded in NOTICE and THIRD_PARTY_NOTICES.md.

Related packages

• JSON-RPC is suited to explicit method calls and internal service APIs.
• OpenAPI models and validates OpenAPI descriptions.