DOCSEARCHbyAlgolia
Submit Docs

json-schema-for-humans

repository·main·Indexed 20 days ago

https://github.com/coveooss/json-schema-for-humans

A tool that transforms JSON schemas into human-readable documentation. It supports multiple output formats, including HTML (JS, JS Offline, Flat) and Markdown (with or without badges and nesting). Configuration can be provided via .json or .yaml files, the Command Line Interface (CLI), or programmatically using a GenerationConfiguration object.

Tokens
86.9K
Snippets
215
Records
504
Agent score
68%

What's inside json-schema-for-humans

  1. Understand the generated Schema Documentation format

    main

    The json-schema-for-humans tool generates human-readable documentation from JSON Schemas. The output typically includes a high-level summary table of the root object and detailed sections for each property.

    Key metadata provided for each property includes:

    • Type: The JSON schema type (e.g., object, string).
    • Required: Indicates if the property is mandatory.
    • Additional properties: Specifies if extra properties are allowed.
    • Default: The default value assigned to the property if not provided.
    • Defined in: The JSON pointer to where the property's schema is defined (e.g., #/definitions/common).
    • Description: A human-readable explanation of the property's purpose.

  2. Navigate the Schema Documentation hierarchy

    main
    The generated schema documentation uses a hierarchical structure to represent the nesting of JSON schema properties. You can navigate from the root object down through nested properties, such as root > objectA > signature, to find specific field definitions. The documentation supports complex schema constructs like oneOf, allOf, and conditional if/then logic, which are represented as distinct levels in the navigation tree.

  3. Reference schema documentation structure

    main

    The generated documentation for JSON Schemas organizes properties by their location in the hierarchy (e.g., root > property_name). It provides a summary table of all top-level properties including their Type, Required status, Pattern, and where they are Defined (via $ref).

    Key features of the documentation include:

    • Definition Tracking: Shows if a property is defined locally (e.g., #/definitions/gift) or in an external file (e.g., references.json#/definitions/string_def).
    • Hierarchy Navigation: Allows drilling down into nested objects and array items.
    • Constraint Visibility: Displays array restrictions like Min items, Max items, and Additional items.

  4. Browse JSON Schema rendition examples

    main

    You can explore how different JSON schemas are rendered using various templates provided by json-schema-for-humans. The examples demonstrate how specific schema features (like additionalProperties, anyOf, or array) appear across different output formats.

    Available Templates

    • JS template: Standard HTML rendering using JavaScript.
    • JS Offline template: HTML rendering designed for offline use.
    • Flat template: A flattened HTML view.
    • Markdown without badge template: Standard Markdown output.
    • Markdown with badges template: Markdown output including visual badges.
    • Nested Markdown (without/with badges): Markdown output that preserves nested structures.

  5. Define Public Key structures for different key types

    main

    The publicKey object is a combining type that varies based on the kty (Key Type) property. Depending on the kty value, different required properties must be provided to satisfy the schema requirements.

    Supported Key Types:

    1. EC (Elliptic Curve)

      • Required Properties:
        • kty: Must be "EC".
        • crv: The curve name. Must be one of: "P-256", "P-384", or "P-521".
        • x: The X coordinate (string). Length must match the curve size (e.g., 66 bytes for "P-521").
        • y: The Y coordinate (string). Length must match the curve size (e.g., 32 bytes for "P-256").

    2. OKP (Octet Key Pair)

      • Required Properties:
        • kty: Must be "OKP".
        • crv: The EdDSA curve name. Must be one of: "Ed25519" or "Ed448".
        • x: The X coordinate (string). Length must match the curve size (e.g., 32 bytes for "Ed25519").

    3. RSA

      • Required Properties:
        • kty: Must be "RSA".
        • n: The RSA modulus (string).
        • e: The RSA exponent (string).

  6. Understand JSON Schema $ref documentation patterns

    main

    The json-schema-for-humans documentation generator visualizes how JSON Schema $ref (references) work across different scopes. When viewing generated documentation, you can identify how properties are defined and linked using several patterns:

    • Internal Definitions: Properties defined within the same file using JSON pointers like #/definitions/name. These are labeled as Defined in.
    • Same Definition: Properties that point to an existing definition, labeled as Same definition as followed by an anchor link.
    • Cross-File References: Properties that reference definitions in external files. These are shown with the filename and path, such as filename.json#/definitions/name or filename.json#/properties/name.
    • Reference Styles: The generator supports various reference styles including slash-separated paths (#/definitions/), dot-notation (file.json#definitions/), and parent-directory navigation (file.json#../definitions/).

    This allows developers to trace the lineage of a schema property back to its source definition, whether it is local or in a remote schema file.

  8. Understand nested JSON Schema structures in documentation

    main

    The documentation uses a hierarchical, breadcrumb-style navigation to represent deeply nested JSON Schema properties. This allows users to trace the exact path from the root object down to specific leaf properties, including those within complex logical constructs like oneOf, allOf, and if/then conditionals.

    Key path components to look for:

    • oneOf > item N: Represents one of several possible schema definitions.
    • allOf > item N: Represents a combination of multiple schema definitions.
    • then: Indicates properties that are required or available only when a specific condition (often defined by an if block) is met.
    • [Required] / [Optional]: Indicates the necessity of the property at that specific level of the schema.

  9. Understand the structure of the `root > storage` property

    main

    The root > storage property is a required combining type used for an fstab entry. It utilizes an anyOf logic, meaning the property must satisfy at least one of the following sub-properties:

    • diskDevice (defined in #/definitions/diskDevice)
    • diskUUID (defined in #/definitions/diskUUID)
    • item 2 (an anonymous object)
    • tmpfs (defined in #/definitions/tmpfs)

    Each of these options is an object type where additional properties are allowed and they are not individually required.

  10. Understand how `anyOf` options are documented in JSON Schema for Humans

    main
    When json-schema-for-humans generates documentation for a schema containing an anyOf combinator, it presents the available options as a list of selectable properties under a combining type. Each option in the anyOf array is treated as a distinct path (e.g., root > storage > anyOf > diskDevice) and is documented with its own type, definition reference, and additional properties status. This allows developers to see exactly which schema definitions are valid alternatives within a single property.

  11. Understand how `oneOf` combining schemas are documented

    main

    When using json-schema-for-humans to document a JSON Schema that utilizes the oneOf combining keyword, the tool generates a structured overview of the possible valid sub-schemas.

    Each option within the oneOf array is listed as a distinct property under the root. The documentation identifies the Type of the sub-schema (e.g., combining, const) and provides the Specific value required to satisfy that branch of the logic. This allows developers to quickly see the different valid shapes a JSON object can take when constrained by oneOf.

  12. Understand `anyOf` property structures in generated schema documentation

    main

    When json-schema-for-humans processes a JSON Schema containing an anyOf combining keyword, it represents the property as a combining type. The documentation lists the available options within that anyOf block, allowing users to see which specific sub-schemas (like diskDevice, diskUUID, or tmpfs) satisfy the requirement.

    In the generated output:

    • The parent property is marked with the type combining.
    • A table lists the individual options available under the anyOf constraint.
    • Each option links to its specific definition or sub-schema details.