Schema Commands

The following commands may be used when working with:

  • Open Contracting Data Standard (OCDS), plus its extensions and profiles

  • Open Contracting for Infrastructure Data Standard (OC4IDS)

  • Beneficial Ownership Data Standard (BODS)

  • Social Investment Data Lab Specification (SEDL)

Optional arguments for all commands (if relevant) are:

--encoding ENCODING

the file encoding

--ascii

print escape sequences instead of UTF-8 characters

--pretty

pretty print output

mapping-sheet

Generates a spreadsheet with all field paths in a JSON Schema.

Required arguments:

  • file the schema file

Optional arguments:

--order-by COLUMN

sort the spreadsheet’s rows by this column

--infer-required

infer whether fields are required (use with OCDS schema)

--extension

patch the release schema with this extension

--extension-field

add an “extension” column for the name of the extension in which each field was defined

--no-inherit-extension

fields defined via $ref properties do not inherit the “extension” value of their parent field

--language

the language to use for the name of the extension

--codelist

add a “codelist” column

--no-deprecated

don’t include deprecated fields

--no-replace-refs

don’t replace schema with $ref properties with the referenced schema

The --extension option must be declared after the file argument. The --extension option accepts multiple values, which can be extension metadata URLs, base URLs and/or download URLs. For example:

ocdskit mapping-sheet release-schema.json --extension \
   https://raw.githubusercontent.com/open-contracting-extensions/ocds_coveredBy_extension/master/extension.json \
   https://raw.githubusercontent.com/open-contracting-extensions/ocds_options_extension/master/ \
   https://github.com/open-contracting-extensions/ocds_techniques_extension/archive/master.zip \
   > mapping-sheet.csv

The --extension-field option can be used with or without the --extension option.

  • If the --extension option is set, then the --extension-field option may be set to any value. In all cases, the result is a mapping sheet with an “extension” column, containing the name of the extension in which each field was defined.

  • If the --extension option is not set, then the --extension-field option must be set to the property in the JSON schema containing the name of the extension in which each field was defined. If there is no such property, then the result is a mapping sheet with no values in its “extension” column.

For a description of the columns of the spreadsheet, see the Mapping Sheet module.

ocdskit mapping-sheet path/to/project-schema.json > mapping-sheet.csv
ocdskit mapping-sheet --infer-required path/to/release-schema.json > mapping-sheet.csv
ocdskit mapping-sheet --order-by path path/to/person-statement.json > mapping-sheet.csv
ocdskit mapping-sheet --infer-required path/to/release-schema.json --extension https://github.com/open-contracting-extensions/ocds_lots_extension/archive/master.zip > mapping-sheet.csv

For the Python API, see ocdskit.mapping_sheet.mapping_sheet().

Note

An error is raised if the --order-by column doesn’t exist.

schema-report

Reports details of a JSON Schema (open and closed codelists, definitions that can use a common $ref in the versioned release schema).

Optional arguments:

--no-codelists

skip reporting open and closed codelists

--no-definitions

skip reporting definitions that can use a common $ref in the versioned release schema

--min-occurrences

report definitions that occur at least this many times (default 5)

cat path/to/release-schema.json | ocdskit schema-report

schema-strict

Adds “minItems” and “uniqueItems” if an array, “minProperties” if an object and “minLength” if a string and “enum”, “format” and “pattern” are not set.

Optional arguments:

--no-unique-items

don’t add “uniqueItems” properties to array fields

--check

check the file for missing properties without modifying the file

ocdskit schema-strict path/to/release-schema.json

set-closed-codelist-enums

Sets the enum in a JSON Schema to match the codes in the CSV files of closed codelists.

ocdskit set-closed-codelist-enums path/to/standard path/to/extension1 path/to/extension2

normalize

Normalizes a denormalized JSON Schema.

Required arguments:

  • file the schema file

Optional arguments:

--fix

fix validation errors

--remove-private-fields

remove _* fields

--remove-fields FIELD

remove specified fields

--root-pattern PATTERN

remove definitions unreachable from names matching this pattern

--ignore-x-keywords

when deduplicating classes, ignore x-* keywords

--ignore-fields FIELD

when deduplicating classes, ignore specified fields

--max-field-prevalence FLOAT

when extracting base classes, ignore fields found in more than this proportion of classes

--base-class-name-prefix

prefix to disambiguate base classes from existing classes

--get-only

if file is OpenAPI Schema, include only schemas used by GET paths

--check

check the file for denormalization without modifying the file

ocdskit normalize path/to/schema.json

Note

The metadata and validation keywords after normalization are illustrative, not representative, of the original schema.

erd

Generates an entity-relationship diagram from a normalized JSON Schema.

Note

Requires the erd extra:

pip install ocdskit[erd]

Required arguments:

  • file the schema file

  • output the output file (Graphviz DOT format)

Optional arguments:

--no-properties

show schema names and relationships only

--max-properties N

truncate schema properties (default: unlimited)

--threshold N

add schemas referenced this many times to a subgraph (default: auto)

--root-pattern PATTERN

never add schemas matching this regex to the subgraph

--cluster PATTERN

force schema names matching this regex into one color cluster (repeatable, evaluated in order)

--ignore-words WORD

when color clustering, ignore these words in schema names

--ignore-before SEP

when color clustering, ignore the parts of schema names before this character

--base-class-name-prefix

prefix to disambiguate base classes from existing classes

-v, --verbose

print verbose output to stderr

ocdskit erd path/to/schema.json schema.dot