DOCSEARCHbyAlgolia
Submit Docs

jsonschema2md

repository·main·Indexed 20 days ago

https://github.com/adobe/jsonschema2md

A suite of tools to convert JSON Schema files into readable Markdown documentation, designed for use with GitHub, Jekyll, and other static site generators. It supports JSON Schema 2019-09 and provides a CLI, a Node.js API, and an npm package (@adobe/jsonschema2md) to programmatically or manually generate documentation including property tables, abstract schema summaries, and constraint details.

Tokens
44.1K
Snippets
109
Records
176
Agent score
67%

What's inside jsonschema2md

  1. Understand the @id property in Identifiable Schemas

    main

    In schemas following the identifiable.schema.json pattern, the @id property serves as a unique identifier for every addressable entity. It is defined as a string that must conform to the URI format according to RFC 3986.

    Property Characteristics:

    • Type: string
    • Constraints: Must be a valid URI.
    • Additional Properties: Allowed.
    • Custom Properties: Forbidden.
    • Abstract: Can be instantiated.
    https://example.com/schemas/identifiable#/properties/@id

  2. Understand extensible schemas and definitions

    main
    An extensible schema is a JSON Schema that contains a definitions section. These definitions can be referenced by other schemas using JSON Schema pointers ($ref). When jsonschema2md processes such a schema, it generates documentation for the definitions, allowing them to be reused and documented as independent entities that can be linked to from other parts of a documentation set.

  3. View property details for a schema object

    main

    For any object defined in a schema, jsonschema2md generates a properties table that lists:

    • Property: The name of the field (linked to its detailed section).
    • Type: The data type (e.g., string, object).
    • Required: Whether the property must be present.
    • Nullable: Whether the value can be null.
    • Defined by: The parent definition or schema component that owns the property.

  4. Reference properties and merged types in generated documentation

    main

    The documentation generator handles several advanced JSON Schema constructs:

    Merged Types

    Logical combinators like or, and, and xor are documented as "merged types". The documentation lists the constituent parts of the logical operation (e.g., "any of", "all of", or "one (and only one) of") and provides links to the specific type definitions involved.

    Pattern Properties

    Properties defined via patternProperties (e.g., int.* or str.*) are explicitly listed in the properties table, showing the pattern used and the type assigned to matching keys.

    Additional Properties

    If additionalProperties is defined in the schema, it is documented as a property, showing its type and constraints.

  5. Understand documentation for complex array types like JoinTypelist

    main
    When an array contains objects that must satisfy specific conditions (one of several possible shapes), the documentation uses a 'Condition' model. For example, JoinTypelist is an array where each item must fulfill either 'Condition 1' (an object with an optional string property foo) or 'Condition 2' (an object with an optional string property bar).

  6. Understand how schema extensions are represented in documentation

    main

    When using jsonschema2md to document schemas that use composition keywords like allOf, the generated documentation identifies whether an abstract object can be instantiated. In the case of an allOf sub-schema, the documentation indicates:

    • Can be instantiated: No (it is an abstract combination of other schemas).
    • Extensible: No.
    • Additional Properties: Allowed.
    • Defined In: A link to the original source schema file.

    This helps developers distinguish between concrete objects they can use in data and abstract logical constraints defined by the schema.

  7. Understand documentation for arrays of objects (e.g., objectlist)

    main

    For arrays containing objects, the documentation specifies the array type (e.g., object[]) and then provides a property table for the objects contained within the array. This table includes the property name, type, and whether the property is required for the object.

    | Property | Type    | Required     |
| -------- | ------- | ------------ |
| `a`      | string  | **Required** |
| `b`      | integer | Optional     |

  8. Reference external definitions in an extending schema

    main

    An extending schema is a JSON Schema that pulls definitions from other schemas using $ref. When using this pattern, the documentation generated by jsonschema2md will link to the external definitions, allowing you to maintain a single source of truth for shared components across multiple schema files.

    {
  "$ref": "https://example.com/schemas/extending#/definitions/third"
}

  9. Understand how 'or' types are rendered in documentation

    main
    When using jsonschema2md to document JSON Schemas, the or keyword (representing an anyOf logical constraint) is rendered as a 'merged type'. The documentation lists the possible types that satisfy the condition, typically as a list of sub-schemas. For example, if a property can be either a string or a number, the generated Markdown will show the property as a merged type and provide links or sections for each specific type definition within the anyOf array.

  10. Understand the generated documentation format

    main

    The jsonschema2md tool generates structured Markdown documentation from JSON Schemas. The output typically includes:

    • Schema Overview: A summary table containing metadata such as Abstract status, Extensibility, Status, Identifiability, Custom Properties, Additional Properties, Access Restrictions, and the source definition link.
    • Type Summary: A high-level view of the schema's root type (e.g., object).
    • Example Payloads: JSON snippets demonstrating valid instances of the schema.
    • Property Tables: A detailed breakdown of all properties, including their Type, Required status, Nullability, and links to their specific definitions.
    • Property Details: Individual sections for each property providing a description, type information, and specific examples for that field.

  11. Understand Pattern Properties Schema documentation

    main
    When using jsonschema2md on a JSON schema that utilizes the patternProperties keyword, the generated documentation will represent the schema's structure based on the regex patterns defined. In the example provided, a schema containing only patternProperties is documented by listing the properties that match the pattern, their types, and their constraints (e.g., whether they are optional or nullable).

  12. How custom properties and definitions are handled in generated documentation

    main

    The jsonschema2md tool supports extensible schemas that include definitions and custom properties.

    • Definitions: Groups of properties defined within a schema can be referenced using standard JSON Schema $ref syntax (e.g., https://example.com/schemas/custom#/definitions/first). The tool generates documentation for these definitions, including property tables that specify Type, Required status, Nullable status, and the source definition.
    • Custom Properties: The tool allows for custom properties within the schema, which are reflected in the generated documentation metadata (e.g., showing that custom properties and additional properties are 'Allowed').