Skip to content

JSON Schema reference

This reference is for data consumers who validate the distribution data and developers who modify the data structures. It explains permitted values and conditional constraints for each JSON Schema. If you first want to understand what each field represents and how it appears in actual data, see the field reference for lenses and related optical products or the mount adapter field reference.

This project's JSON Schemas conform to JSON Schema Draft 2020-12. The published URL namespace is divided into lenses and related optical products, mount adapters, and shared definitions. The complete set of JSON Schemas uses one schema version, recorded in the distribution data as schemaVersion.

Choose a JSON Schema for your purpose

The first page to open depends on the type and scope of the data you want to inspect.

What you want to inspect Start with
The complete Lens Full or Lens Light distribution dataset-full or dataset-light
One product in Lens Full or Lens Light product-full or product-light
One canonical record for a lens or related optical product product-record
The complete Full distribution for mount adapters dataset-full
One product in the Full mount adapter distribution adapter-full
One canonical mount adapter record adapter-record
A research result for a product candidate Lenses and related optical products or mount adapters
IDs and display metadata embedded in distributions reference-data

How to read field tables and constraints

On each page, field tables use "Path" for the location in the JSON document, "Type/value" for permitted data types and fixed values, and "Meaning" for the role of the field.

  • [] denotes an array. For example, products[] refers to each element in the products array.
  • "A or null" means that a field may contain either a value of type A or null.
  • {} denotes an empty object with no properties.
  • Literal true, false, and null values, enumerated values, and JSON keys are shown as code.

The type tables use the following names for JSON types.

Term JSON or JSON Schema representation
String string
Number number
Integer integer
Object object
Boolean boolean
Array array
Enumerated value A value permitted by a JSON Schema enum; not a separate JSON type

When [] follows a type name, it denotes an array whose elements have that type. All integers use the I-JSON safe integer range, with an upper bound of 9007199254740991. Fields that permit negative values have a lower bound of -9007199254740991. If an individual table specifies a narrower range, that constraint takes precedence.

Each reference page explains the corresponding JSON Schema in prose and tables. Consult the JSON Schema file for the exact types, required fields, permitted values, and conditional constraints. When modifying repository source files, use hatch run validate to check rules that JSON Schema alone cannot express. Repository validation covers each schema's Draft 2020-12 validity, $id and $ref values, file names and locations, ID and registry references, and relationships between files.

Published URLs and versions

Each JSON Schema $id is a published URL that includes the schema version and namespace. The current schema version is 1.0.0, and the URLs use the following forms.

  • Lenses and related optical products: https://cercidiphyllum.jp/schemas/1.0.0/lenses/<schema-file>
  • Mount adapters: https://cercidiphyllum.jp/schemas/1.0.0/adapters/<schema-file>
  • Shared definitions: https://cercidiphyllum.jp/schemas/1.0.0/shared/<schema-file>

The contents of a published versioned URL and its JSON Schema never change. When the data structure or its constraints change, schemaVersion is updated and previous versions remain published. See Use the distribution data for version checks performed by data consumers.

Shared

The shared JSON Schemas validate definitions used by both datasets and reference information embedded in distribution JSON.

JSON Schema What it validates
shared-definitions IDs, numbers, measurement conditions, and other definitions referenced by multiple JSON Schemas
reference-data ID-to-display-metadata maps embedded at the root of each distribution JSON

Lenses and related optical products

For lenses and related optical products, separate JSON Schemas validate distribution data, canonical records, and research results.

JSON Schema What it validates
dataset-full The complete Lens Full distribution
dataset-light The complete Lens Light distribution
product-full One product in the Lens Full products[] array
product-light One product in the Lens Light products[] array
product-record One canonical record under data/records/lenses/
product-components Shared blocks for identity, lifecycle, mount, physical details, and other information used by multiple product types
product-type-lens The lens block for a lens
product-type-teleconverter The teleconverter block for a teleconverter
product-type-pinhole The pinhole block for a pinhole product
research-result One research result under research/results/lenses/

Mount adapters

Mount adapters use a data structure separate from lenses and related optical products, and there is no Light edition.

JSON Schema What it validates
dataset-full The complete Full distribution for mount adapters
adapter-full One product in the Full mount adapter distribution's adapters[] array
adapter-record One canonical record under data/records/adapters/
adapter-components Shared blocks for mount conversion, electronics, optics, physical details, and other information
research-result One research result under research/results/adapters/

JSON Schema license

The JSON Schema files under schemas/ are licensed under the MIT License. The SPDX-FileCopyrightText and SPDX-License-Identifier: MIT lines in each file's $comment also apply only to the JSON Schema file. Research results, canonical records, registries, and distribution data validated by those JSON Schemas are licensed under CC BY 4.0.