{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Open Know-How manifest schema for Helpful Engineering",
    "type": "object",
    "$comment": "Manually converted from https://standards.internetofproduction.org/pub/okh/release/1 spec. Please see field comments for any departures from the spec",
    "properties": {
        "date-created": {
            "type": "string",
            "format": "date",
            "description": "Indicates the date the manifest was originally created"
        },
        "date-updated": {
            "type": "string",
            "format": "date",
            "description": "Indicates the date the manifest was last edited"
        },
        "manifest-author": {
            "$ref": "#/definitions/Contact",
            "description": "States the person who has created and is responsible for the content in the manifest",
            "$comment": "The standardized Contact definition includes a social field that is not included for manifest author in the spec. Feels like a mistake to have slightly different definitions for contact style fields"
        },
        "title": {
            "type": "string",
            "description": " A title to identify the thing"
        },
        "description": {
            "type": "string",
            "description": "Describes the thing"
        },
        "intended-use": {
            "type": "string",
            "description": " Informs the maker for what purpose the designer intends the thing to be used. In particular, make reference to the context and type of users"
        },
        "keywords": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "description": "Provides a small number of terms that can be used to help identify"
        },
        "project-link": {
            "type": "string",
            "format": "uri",
            "description": "Where the thing or associated project has a web presence that is separate from the documentation (e.g. a marketing page), links to the web resource",
            "$comment": "Should this be a SingleFileReference like other links? Also, there's a requirement in the spec to specify either project link or documentation home which has not been captured in this schema"
        },
        "health-safety-notice": {
            "type": "string",
            "description": " Highlight health and safety risks and/or necessary precautions that the maker should be aware of as part of the decision to make the thing"
        },
        "contact": {
            "$ref": "#/definitions/Contact",
            "description": "Provides a point of contact for people who wish to discuss the thing"
        },
        "contributors": {
            "type": "array",
            "items": {
                "$ref": "#/definitions/Contact"
            },
            "description": "Credits the contributors to the know-how",
            "$comment": "Like manifest, uses the common Contact definition which adds social field"
        },
        "image": {
            "type": "string",
            "format": "uri",
            "description": "Provides a graphical representation of the thing"
        },
        "version": {
            "oneOf": [
                {
                    "type": "string"
                },
                {
                    "type": "number"
                }
            ],
            "description": "Defines the version of the thing that is represented by this manifest",
            "$comment": "Added number alternative due to real world microscope okh file"
        },
        "development-stage": {
            "type": "string",
            "description": "Indicates the maturity of the design and documentation development"
        },
        "made": {
            "type": "boolean",
            "description": "Indicates whether the thing has been made and verifies that it is makeable"
        },
        "made-independently": {
            "type": "boolean",
            "description": "Indicates whether the thing has been made using the documentation by someone who was not a contributor to the design or documentation and, therefore, verifies that the documentation is sufficient to make the thing"
        },
        "standards-used": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "standard-title": {
                        "type": "string",
                        "description": "Title of the standard used in developing the design or documentation"
                    },
                    "publisher": {
                        "type": "string",
                        "description": "Publisher of the standard"
                    },
                    "reference": {
                        "type": "string",
                        "description": "Reference indentifier of the standard"
                    },
                    "certification": {
                        "$ref": "#/definitions/Certification",
                        "description": "If certification has been granted confirming compliance with the standard",
                        "$comment": "Unclear from spec if this field is intended to support multiple certifications. Assuming single since the parent field is an array"
                    }
                },
                "required": [
                    "standard-title"
                ]
            }
        },
        "derivative-of": {
            "$ref": "#/definitions/OkhReference",
            "description": "Where the thing is a derivative of a different thing (e.g. the documentation has been forked), links to the original thing",
            "$comment": "standardized definition of OkhReference with manifest-is-translation definition that includes a language field"
        },
        "variant-of": {
            "$ref": "#/definitions/OkhReference",
            "description": "Where the thing is a variant, links to the original",
            "$comment": "standardized definition of OkhReference"
        },
        "sub": {
            "$ref": "#/definitions/OkhReference",
            "description": "Where the design uses sub-components, sub-assemblies etc that are also available as open know-how, links to the documentation",
            "$comment": "standardized definition of OkhReference"
        },
        "license": {
            "type": "object",
            "properties": {
                "documentation": {
                    "type": "string"
                },
                "hardware": {
                    "type": "string"
                },
                "software": {
                    "type": "string"
                }
            },
            "description": "States the licenses under which the thing is made available",
            "$comment": "At least one license is required, but this is not captured by the schema."
        },
        "licensor": {
            "$ref": "#/definitions/Contact",
            "description": "States who is licensing the thing.",
            "$comment": "standardized definition of Contact"
        },
        "documentation-home": {
            "type": "string",
            "format": "uri",
            "description": "Provides a URL entry point to the documentation",
            "$comment": "requirement to specify at least one of project-link or documentation-home fields is not captured in schema"
        },
        "archive-download": {
            "type": "string",
            "format": "uri",
            "description": "Links to a location from which the full documentation can be downloaded as an archive (e.g. zip file)"
        },
        "design-files": {
            "$ref": "#/definitions/MultipleFilesReference",
            "description": "Links to design files"
        },
        "schematics": {
            "$ref": "#/definitions/MultipleFilesReference",
            "description": "Links to schematics"
        },
        "bom": {
            "$ref": "#/definitions/SingleFileReference",
            "description": "Links to the bill of materials",
            "$comment": "Spec defines this as a link, but the sample OKH's I've seen specify this directly as a string. Also, standardized link to share design-files definition"
        },
        "tool-list": {
            "$ref": "#/definitions/SingleFileReference",
            "description": "Links to a list of tools required to make the thing",
            "$comment": "Similar change to bom"
        },
        "making-instructions": {
            "$ref": "#/definitions/MultipleFilesReference",
            "description": "Links to the making instructions, e.g. assembly instructions"
        },
        "manufacturing-files": {
            "$ref": "#/definitions/SingleFileReference",
            "description": "Links to the manufacturing files, such as 3D printing files"
        },
        "risk-assessment": {
            "$ref": "#/definitions/MultipleFilesReference",
            "description": "Links to the risk assessment"
        },
        "tool-settings": {
            "$ref": "#/definitions/MultipleFilesReference",
            "description": "Links to settings for tools and machines"
        },
        "quality-instructions": {
            "$ref": "#/definitions/MultipleFilesReference",
            "description": "Links to instructions for testing and/or quality management"
        },
        "operating-instructions": {
            "$ref": "#/definitions/MultipleFilesReference",
            "description": "Links to instructions for operating the thing"
        },
        "maintenance-instructions": {
            "$ref": "#/definitions/MultipleFilesReference",
            "description": "Links to instructions for operating the thing"
        },
        "disposal-instructions": {
            "$ref": "#/definitions/MultipleFilesReference",
            "description": "Links to instructions for disposing the thing at the end of its life"
        },
        "software": {
            "$ref": "#/definitions/MultipleFilesReference",
            "description": "Links to source code repository or software executables used by the thing"
        },
        "manifest-language": {
            "$ref": "#/definitions/Language",
            "description": "States the language in which the manifest has been produced"
        },
        "documentation_language": {
            "$ref": "#/definitions/Language",
            "description": "States the language in which the documentation has been produced"
        },
        "manifest-is-translation": {
            "$ref": "#/definitions/OkhReference",
            "description": "Where this manifest is a translation of another, links to the original"
        },
        "documentation-is-translation": {
            "$ref": "#/definitions/OkhReference",
            "description": "Where this manifest references documentation that is translated, links to the original"
        },
        "product-atom": {
            "$ref": "#/definitions/Atom",
            "description": "describes the output of this OKH as an atom"
        },
        "bom-atoms": {
            "type": "array",
            "items": {
                "$ref": "#/definitions/Atom"
            },
            "description": "describes the bill of materials to make this OKH as a an array of atoms"
        },
        "tool-list-atoms": {
            "type": "array",
            "items": {
                "$ref": "#/definitions/Atom"
            },
            "description": "describes the tools needed to make this OKH as a an array of atoms"
        },
        "bom-output-atoms": {
            "type": "array",
            "items": {
                "$ref": "#/definitions/Atom"
            },
            "description": "describes additional outputs of this OKH besides the product-atom"
        }
    },
    "required": [
        "title",
        "description"
    ],
    "definitions": {
        "Atom": {
            "type": "object",
            "properties": {
                "identifier": {
                    "type": "string"
                },
                "description": {
                    "type": "string"
                },
                "link": {
                    "type": "string",
                    "format": "uri"
                }
            },
            "required": [
                "description",
                "identifier"
            ],
            "additionalProperties": false,
            "title": "Atom"
        },
        "Certification": {
            "type": "object",
            "properties": {
                "certifier": {
                    "type": "string",
                    "description": "Individual or organisation granting the certification. Use \"Self\" for self-certification"
                },
                "date-awarded": {
                    "type": "string",
                    "format": "date",
                    "description": "Date certification was granted"
                },
                "link": {
                    "type": "string",
                    "format": "uri",
                    "description": "Link to evidence of certification (e.g. certificate)"
                }
            },
            "required": [
                "certifier",
                "date-awarded",
                "link"
            ],
            "description": "If certification has been granted confirming compliance with the standard"
        },
        "Contact": {
            "type": "object",
            "properties": {
                "name": {
                    "type": "string"
                },
                "affiliation": {
                    "type": "string"
                },
                "email": {
                    "type": "string",
                    "format": "email"
                },
                "social": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "platform": {
                                "type": "string"
                            },
                            "user-handle": {
                                "type": "string"
                            }
                        },
                        "required": [
                            "platform",
                            "user-handle"
                        ]
                    }
                }
            },
            "required": [
                "name"
            ],
            "$comment": "Spec constraint that Contact specifies at least one email address or social media user handle is not implemented in this schema"
        },
        "OkhReference": {
            "type": "object",
            "properties": {
                "title": {
                    "type": "string",
                    "description": "Title of the original"
                },
                "manifest": {
                    "type": "string",
                    "format": "uri",
                    "description": "OKH manifest location"
                },
                "web": {
                    "type": "string",
                    "format": "uri",
                    "description": "web presence location"
                },
                "lang": {
                    "$ref": "#/definitions/Language",
                    "description": "language of original"
                }
            },
            "required": [
                "title"
            ]
        },
        "MultipleFilesReference": {
            "oneOf": [
                {
                    "$ref": "#/definitions/SingleFileReference"
                },
                {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/SingleFileReference"
                    }
                }
            ],
            "$comment": "Added support for single item w/o array syntax for user productivity"
        },
        "SingleFileReference": {
            "oneOf": [
                {
                    "type": "string"
                },
                {
                    "type": "object",
                    "properties": {
                        "title": {
                            "type": "string"
                        },
                        "path": {
                            "type": "string",
                            "format": "uri"
                        }
                    },
                    "required": [
                        "path"
                    ]
                }
            ],
            "$comment": "Unclear from spec what this definition should be. Used path/title object def from other examples like making-instructions"
        },
        "Language": {
            "type": "string",
            "description": "ISO 639 language code. Use the Alpha-2 code where available. Optionally, the ISO 3166 country code may be included.",
            "$comment": "[language-code]-[region]"
        }
    }
}