Schemas

Warning

These schemas are subject to change in future releases.

JSON schemas of the formalized data structures used in the Canopy API are listed here. These schema attempts to adhere to the 2020-12 version of the JSON Schema specification for python as implemented by the jsonschema package.

The command line tool check-jsonschema can be used to validate JSON files against these schemas.

Template Document

JSON schema: ParsedTemplateDocument.json

The following validation rules, which cannot be expressed in JSON Schema, apply to this schema:

• type:

  • Where the field type is “Table” the rows must contain at least one row and number_of_table_columns must be greater than zero.

This schema is used for the import/export of:

• Report templates

• Statement of work templates

Template Methodology

JSON schema: ParsedTemplateMethodology.json

This schema is used for the import/export of:

• Methodology templates

The following validation rules, which cannot be expressed in JSON Schema, apply to this schema:

• custom_fields:

  • Each name must match a methodology item custom field that exists and is enabled. A value whose name is unknown or whose field is disabled is skipped on import, and is omitted from the export.

Template Taxonomy

JSON schema: ParsedTemplateTaxonomy.json

This schema is used for the import/export of:

• Taxonomy templates

Template Findings

JSON schema: ParsedTemplateFindingList.json

This schema is used for the import/export of:

• Findings Knowledge Base

Terminology note: Findings Knowledge Base (KB) is a collection of Template Findings.

Methodology

JSON schema: ParsedMethodology.json

This schema is used for the import/export of:

• Methodologies

Unlike the template schemas above, this schema captures a methodology as recorded within a phase, including its items and their results. The export is the format the import accepts, so an exported methodology can be edited and imported back.

Rich text fields are exported as Markdown, with inline images replaced by a placeholder, and are converted back to HTML on import. A field still holding that placeholder is left as recorded, because a document cannot carry the image the placeholder stands for — so an unedited export can be imported back without replacing an image with the placeholder’s own text.

An import writes every value a document carries, except where a rule below says otherwise. A blank or absent value is never written, so a partly filled document leaves every value it does not fill as recorded.

The following validation rules, which cannot be expressed in JSON Schema, apply to this schema:

• uuid:

  • The methodology uuid decides what an import applies to: a document naming a methodology of the target phase updates it, and one carrying no uuid records a new methodology.

  • A methodology uuid the target phase does not hold is rejected, since the document names something that should already be there.

  • When a new methodology is recorded, every item uuid is ignored and fresh identifiers are minted, so the same document can be imported onto as many phases as needed.

  • When an existing methodology is updated, items are matched on uuid within that methodology. An item whose uuid matches nothing is skipped, and an item carrying no uuid at all is appended.

  • An item the document does not mention is left alone. An import never deletes.

• name and description:

  • The methodology’s own name and description are written by an update when they are not blank. Its status_choices and enabled_fields are left as recorded, because dropping a status the items still hold would strand them.

• order:

  • Orders the items of a new methodology, defaulting to an item’s position within this document. The items are then renumbered to a dense range that keeps that relative order, since a document may number some of its items and leave the rest to their position.

  • Ignored by an update, which keeps the position of an item it matches and appends one it adds, in the order this document lists it.

• status:

  • Must be one of the target methodology’s status_choices, which is the one rule here that rejects the document rather than skipping the value: an import whose statuses were silently dropped would look like it had worked.

  • A methodology offering no status_choices accepts any status.

  • An added item carrying no status is recorded with the first of the methodology’s status_choices.

• enabled_fields:

  • Each entry of a new methodology’s list should be one of “description”, “subcategory”, “level”, “references”, “riskrating”, “notes” or “guide”. An entry naming anything else is dropped.

• custom_fields:

  • Each name should match a methodology item custom field that exists and is enabled. A value whose name is unknown or whose field is disabled is skipped on import, and is omitted from the export.

• assets:

  • Each asset should name an asset belonging to the target phase; the uuid is ignored. A name matching no asset of that phase is skipped, since the document names the assets of the phase it was exported from.

  • An import adds asset links, it never removes them.

• findings:

  • Ignored on import. Finding links are created by the Knowledge Base auto-fail flow, never by an import.

• categories:

  • Recomputed from the categories of the items on import, so a category no item uses is dropped and one an item introduces is added.

An update writes the content an item describes as well as its results, so an exported document can be edited and imported back to correct an item’s name, reference or guide as much as its status or notes.

Canopy Tool Data

JSON schema: CanopyToolData.json

This schema represents the internal data structure used for tool imports.

System Data

JSON schema: ParsedSystemDataContainer.json

The following import validation rules, which cannot be expressed in JSON Schema, apply to this schema:

• custom_fields:

  • allow_lookup can only be set if the custom field type is “Text”.

  • lookup_label may only be set when allow_lookup is “true”.

  • children field may only be set when type is “Group” and the child custom fields may not have children of their own.

  • is_content_field will only be set where the model_name is “FindingCustomField”. Additionally where the type is “Rich Text” is_content_field will be imported as “true” regardless of the value in the import file.

• settings:

  • value must be a valid JSON string where setting is one of the following:

    • “DOCUMENT_CLASSIFICATIONS”

    • “TINYMCE_STYLE_FORMATS”

This schema is used for the import/export of:

• Data Import/Export