A complement to JSON Schema that describes the shape of resources in a way that is optimized for human comprehension and code-generation — what fields exist, how they relate, and what each is for — rather than for runtime validation. JSON Structure files sit alongside JSON Schema files in the same repository; the schema enforces correctness, the structure communicates intent. Together they form a richer picture of a resource than either provides alone.

Also known as: Structure, Resource Structure

Example

- type: JSONStructure
  url: json-structure/example-resource-structure.json

Standards

• Community JSON Structure (community spec)
• IETF (draft) JSON Schema 2020-12
• ECMA ECMA-404 — The JSON Data Interchange Syntax

Media Types

• application/json — JSON Structure files are typically served as application/json.

Risk & Compliance

Security: Structure documents describe the surface area of an API's resources in detail; treat them as you would JSON Schema or OpenAPI. Field names that suggest internal-only attributes (debug, internal_id, source_record) should be omitted from public structure documents, not just hidden behind authorization.

Tools

• openapi-generator — Codegen — can consume structure-equivalent JSON (Apache-2.0)
• quicktype — Generates types from JSON examples and schemas (Apache-2.0)

Suggested Metrics

• structure_coverage — Share of resources in an API that have a published JSON Structure file.
• structure_schema_parity — Count of resources with a Structure file but no parallel JSON Schema (or vice versa).
• structure_freshness_days — Days since each Structure file was last updated against the resource it describes.

Example Implementations

• API Evangelist catalogs — The api-evangelist provider catalog co-locates `json-structure/-structure.json` alongside `json-schema/-schema.json`, `examples/`, and `json-ld/` for each resource.

Related Properties

• Json schema
• Openapi
• Asyncapi
• Vocabulary

Tags

• Machine-Readable
• Schema
• Resources

All Community Properties