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 package has a stable v1 API. Its supported protocol surface is conformance-tested and production code is held to meaningful 100% statement coverage. Read the compatibility policy before adopting a revision.

Requirements

• Go 1.26.6 or later

Installation

go get github.com/faustbrian/go-jsonapi

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

Run make check before submitting a change. This enforces formatting, static analysis, race tests, meaningful 100% coverage, fuzz smoke, benchmarks, documentation, and vulnerability scanning.

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.