From 666c1f019c275a65fe96246a20e5bd3fbd73a8dd Mon Sep 17 00:00:00 2001 From: Sam Thursfield Date: Fri, 31 Jul 2015 12:07:40 +0100 Subject: Add schemas for Baserock definitions format See schemas/README.schemas for information. Change-Id: I6c384692dbf70017a3ece2ed56c1f8cbe60b493d --- README | 4 +- schemas/README.schemas | 137 ++++++++++++++++++++ schemas/baserock.owl | 295 ++++++++++++++++++++++++++++++++++++++++++++ schemas/chunk.json-schema | 116 +++++++++++++++++ schemas/cluster.json-schema | 64 ++++++++++ schemas/stratum.json-schema | 99 +++++++++++++++ schemas/system.json-schema | 59 +++++++++ scripts/yaml-jsonschema | 50 ++++++++ 8 files changed, 822 insertions(+), 2 deletions(-) create mode 100644 schemas/README.schemas create mode 100644 schemas/baserock.owl create mode 100644 schemas/chunk.json-schema create mode 100644 schemas/cluster.json-schema create mode 100644 schemas/stratum.json-schema create mode 100644 schemas/system.json-schema create mode 100755 scripts/yaml-jsonschema diff --git a/README b/README index 887332d7..ed52d721 100644 --- a/README +++ b/README @@ -9,7 +9,8 @@ this repo and develop your own systems directly within it, or use it as a reference point when developing your own set of definitions. These definitions follow the Baserock definitions format, which is described at -. +, and also partly in the schemas/ +subdirectory. The systems listed in the systems/ directory are example systems that build and run at some point. The only ones we can be sure @@ -17,7 +18,6 @@ that still build in current master of definitions are the ones that we keep building in our ci system; they are listed in http://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/definitions.git/tree/clusters/ci.morph - Keeping up to date ------------------ diff --git a/schemas/README.schemas b/schemas/README.schemas new file mode 100644 index 00000000..a7789187 --- /dev/null +++ b/schemas/README.schemas @@ -0,0 +1,137 @@ +Schemas for the Baserock definitions format +=========================================== + +The starting point for learning about the Baserock definitions format is the +wiki page at . + +The schemas/ directory in the Baserock reference definitions.git repository is +the canonical home for some schemas which describe the format in a +machine-readable way. + +There are two parts to 'Baserock definitions'. The 'Baserock data model' is an +abstract vocabulary for describing how to build, integrate and deploy software +components. The 'Baserock definitions YAML representation format' is a +serialisation format for the data model, which lets you write YAML files +describing how to build, integrate and deploy software components. + +If you want to make the YAML files easier to deal with, you only need +to care about the JSON-Schema schemas and anything that parses the YAML files. + +If you want to write a new tool to build, visualise, analyse or otherwise +process Baserock definitions in some way, you can ignore the syntax altogether, +use a pre-existing parser, and just think in terms of the data +model. + +If you want to change the data model, you still have quite a difficult job, +but at least it should be simple to write a translation layer on top of an +existing parser so that you can interpret all the existing Baserock reference +system definitions in terms of your new data model. + + +The Baserock definitions YAML representation format +--------------------------------------------------- + +YAML itself is a syntax for representating data as text. The YAML specification +is at . + +The data needs to be structured in a certain way for it to make sense as +Baserock build/integration/deployment instructions. We have used JSON-Schema +to describe the required layout of the data. + +The JSON-Schema standard is described at . The +JSON-Schema language was designed for use with JSON, which is another syntax +for representing data as text, which happens to be a subset of YAML. We have +found so far that JSON-Schema works well with YAML, at least when using the +Python 'jsonschema' module. + +Definitions are represented by files with a '.morph' extension. There are four +different kinds: 'chunk', 'stratum', 'system', and 'cluster'. Each of these is +described with a different .json-schema file. It is possible to merge all these +into one file, and use the 'oneOf' field to say that any .morph file should +match exactly one of the layouts. The only issue with this approach is that +the Python 'jsonschema' model will give you totally useless errors if anything +is invalid (along the lines of " is not valid under any of +the given schemas"). So for now they are separate. + + +Tools for working with the Baserock YAML schemas +------------------------------------------------ + +You can use `scripts/yaml-jsonschema` to validate .morph files against the +schemas. For example: + + scripts/yaml-jsonschema schemas/cluster.json-schema clusters/*.morph + + +The Baserock data model +----------------------- + +The best way to represent information on disk may be a pretty inefficient way +to represent that data in a computer's memory. Likewise, the way a program +stores data internally may be totally impractical for people to edit directly. + +The file `baserock.owl` is an initial effort to describe the Baserock data +model independently of any syntax or representation. + +We use the W3C standard Web Ontology Language (OWL), combined with the much +simpler RDF Schema language. Together, this allows defining the vocabulary we +can use to define build, integration and deployment instructions. There are +various ways to represent OWL 'ontologies'; `baserock.owl` uses a +representation format named Turtle, which is designed to be convenient for +hand-editing. + +The current data model is very closely tied to the current syntax, but we are +looking to change this and make it much more generic. This will involve +removing the current 'Chunk', 'Stratum', 'System' and 'Cluster' classes, and +adding something like 'thing with build instructions' and 'thing that contains +other things' instead. Name suggestions are welcome :-) + +It's useful to consider existing OWL and RDF Schema vocabularies that are +related to the Baserock data model. In future we can link the Baserock +reference system definitions with related data published elsewhere on the Web. +Here is an incomplete list: + + - Description of a Project (DOAP): https://github.com/edumbill/doap + - Software Ontology: https://robertdavidstevens.wordpress.com/2014/06/19/the-software-ontology-swo/ + - Software Packet Data Exchange (SPDX): https://spdx.org/about-spdx/what-is-spdx + + +Tools for working with the Baserock data model schema +----------------------------------------------------- + +It's difficult to find to a short, relevant 'getting started' guide. The +website http://www.linkeddata.org/ has a lot of background that should be +useful. + +The `rapper` commandline tool, which comes as part of the 'raptor2' C library, +is helpful for converting from one syntax to another, and checking if +`baserock.owl` is valid Turtle syntax. The 'raptor2' homepage is +. + +To check the syntax of `baserock.owl` using `rapper`: + + rapper -i turtle schemas/baserock.owl + + +Omissions / TODO items +---------------------- + +- Device nodes: chunk .morph files can list a set of device nodes. In + `chunk.json-schema` this is recognised, but in `baserock.owl` it is missing. + +- 'Lorry' mirroring instructions. These contain information on where 'upstream' + source code is kept, which should be considered part of the data model. A + JSON schema may be better off in lorry.git or + baserock/local-config/lorries.git. + +- Metadata in built systems. This is currently not standardised at all. + + +Comments +-------- + +As far as I know, Baserock is the first project to treat build, integration and +deployment instructions as data rather than code. If you have questions about +the schemas, the definitions format, or the overall approach, and they aren't +answered here or in , then please ask on +the baserock-dev@baserock.org mailing list. diff --git a/schemas/baserock.owl b/schemas/baserock.owl new file mode 100644 index 00000000..d699940c --- /dev/null +++ b/schemas/baserock.owl @@ -0,0 +1,295 @@ +# Copyright (C) 2015 Codethink Limited +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; version 2 of the License. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License along +# with this program. If not, see . + + +# This schema describes the Baserock data model. It describes how the data +# can be represented in computer memory, it doesn't specify anything about +# how it should be stored on disk or transferred. +# +# Please see README.schemas, and http://wiki.baserock.org/definitions/current/ +# for more information. +# +# This is not a brilliant schema, in Linked Data terms, because it's using +# Baserock-specific terminology and a rigid layout, instead of being a generic +# vocabulary for describing how to assemble software. However, it maps closely +# to the format that the existing Baserock reference system definitions use. +# We hope to produce a simpler and more flexible 2.x version of this schema in +# future. + + +# Partial OWL and RDF Schema glossary: +# +# domain: the set of objects that a can have a property. +# range: the set of possible values for a property. +# +# ObjectProperty: +# a property whose value must be another resource. +# DatatypeProperty: +# a property whose value is one of the datatype defined by XML Schema ("xsd") +# FunctionalProperty: +# a property which can only have one value per resource +# InverseFunctionalProperty: +# a property which can only have one resource per value + + +# Metadata + +@prefix : . +@prefix owl: . +@prefix rdfs: . +@prefix rdf: . +@prefix xsd: . +@prefix dc: . + +: a owl:Ontology ; + dc:title "Schema for Baserock data model" ; + dc:creator "The Baserock Project" ; + # Versioned according to Semantic Versioning http://www.semver.org/ + owl:versionInfo "0.9.0" . + + +## Entities + +# Source definitions + +:Morphology a owl:Class ; + rdfs:comment "A definition file." . + +:Cluster a owl:Class ; + rdfs:subClassOf :Morphology ; + rdfs:comment "Instructions for deploying one or systems." ; + owl:disjointWith :System, :Stratum, :Chunk . + +:System a owl:Class ; + rdfs:subClassOf :Morphology ; + rdfs:comment "A collection of strata in a form that can be executed." ; + owl:disjointWith :Cluster, :Stratum, :Chunk . + +:Stratum a owl:Class ; + rdfs:subClassOf :Morphology ; + rdfs:comment "A set of related chunks." ; + owl:disjointWith :Cluster, :System, :Chunk . + +:Chunk a owl:Class ; + rdfs:subClassOf :Morphology ; + rdfs:comment "An individual component, that can be built from a Git repository." ; + owl:disjointWith :Cluster, :System, :Stratum . + +# Container contents + +:SystemDeployment a owl:Class ; + rdfs:comment "Information for deploying one system of a cluster." . + +:ChunkReference a owl:Class ; + rdfs:comment "An instance of a chunk within a stratum." . + +# Products (for artifact split rules). + +:Artifact a owl:Class ; + rdfs:comment "One part of the result of building a morphology. The output of a build is split according to patterns, so there are multiple artifacts produced for a given source." . + +:StratumArtifact a owl:Class ; + rdfs:subClassOf :Artifact ; + rdfs:comment "Part of the result of building a stratum." ; + owl:disjointWith :ChunkArtifact. + +:ChunkArtifact a owl:Class ; + rdfs:subClassOf :Artifact ; + rdfs:comment "Part of the result of building a chunk." ; + owl:disjointWith :StratumArtifact. + + +## Shared properties + +# 'name' becomes part of the URL when we import definition .morph files as RDF, +# so it doesn't need a property. + +# Use dc:description for 'description', see: +# http://dublincore.org/documents/2012/06/14/dcmi-terms/?v=terms#terms-description + + +## Cluster-specific properties + +:containsSystemDeployment a owl:ObjectProperty ; + rdfs:domain :Cluster ; + rdfs:range :SystemDeployment ; + owl:minCardinality 1 . + + +## SystemDeployment-specific properties + +:deploysSystem a owl:ObjectProperty , owl:FunctionalProperty ; + rdfs:domain :SystemDeployment ; + rdfs:range :System . + +:hasLabel a owl:DatatypeProperty , owl:FunctionalProperty ; + rdfs:domain :SystemDeployment ; + rdfs:range xsd:string . + +:hasType a owl:DatatypeProperty , owl:FunctionalProperty ; + rdfs:domain :SystemDeployment ; + rdfs:range xsd:string ; + rdfs:comment "The .write extension used to perform the deployment." . + +:hasLocation a owl:DatatypeProperty , owl:FunctionalProperty ; + rdfs:domain :SystemDeployment ; + rdfs:range xsd:string ; + rdfs:comment "Deployment location. This is passed to the selected .write extension" . + +# FIXME: this is actually a key-value mapping, how do you do that in RDF properly? +:hasConfigurationSetting a owl:DatatypeProperty ; + rdfs:domain :SystemDeployment ; + rdfs:range xsd:string ; + rdfs:comment "Arbitrary key=value pair that is set in the environment of the .configure and .write extensions during deployment." . + + +## System-specific properties + +:containsStratumArtifact a owl:ObjectProperty ; + rdfs:domain :System ; + rdfs:range :StratumArtifact ; + owl:minCardinality 1 . + +# A build tool will only understand a certain set of architectures, but I think +# that should not be part of the data model. +:hasArchitecture a owl:DatatypeProperty , owl:FunctionalProperty ; + rdfs:domain :System ; + rdfs:range xsd:string . + +:hasConfigurationExtension a owl:DatatypeProperty ; + rdfs:domain :System ; + rdfs:range xsd:string ; + rdfs:comment "A .configure extension to be run when with system is deployed." . + + +## Stratum-specific properties + +:producesStratumArtifact a owl:ObjectProperty , rdf:Seq ; + rdfs:domain :Stratum ; + rdfs:range :StratumArtifact ; + rdfs:comment "iDescribes how this artifact is split once all chunks are built." . + +:hasStratumBuildDependency a owl:ObjectProperty ; + rdfs:domain :Stratum ; + rdfs:range :Stratum . + +:containsChunkReference a owl:ObjectProperty ; + rdfs:domain :Stratum ; + rdfs:range :ChunkReference ; + owl:minCardinality 1 . + + +## ChunkReference-specific properties + +:refersToChunk a owl:ObjectProperty , owl:FunctionalProperty ; + rdfs:domain :ChunkReference ; + rdfs:range :Chunk . + +:repo a owl:DatatypeProperty , owl:FunctionalProperty ; + rdfs:domain :ChunkReference ; + rdfs:range xsd:string ; + rdfs:comment "Git repo that this chunk's build instructions should be run in. Can be a keyed URL according to the repo-alias mapping, which isn't currently defined in this data model." . + +:ref a owl:DatatypeProperty , owl:FunctionalProperty ; + rdfs:domain :ChunkReference ; + rdfs:range xsd:string ; + rdfs:comment "Ref of the Git repo that should be checked out before building. Usually a SHA1." . + +:unpetrifyRef a owl:DatatypeProperty , owl:FunctionalProperty ; + rdfs:domain :ChunkReference ; + rdfs:range xsd:string ; + rdfs:comment "Name of the ref that should be checked out (useful when 'ref' is a SHA1 to keep track of the actual branch/tag name)." . + +:hasChunkBuildDependency a owl:ObjectProperty ; + rdfs:domain :ChunkReference ; + rdfs:range :Chunk . + +:prefix a owl:DatatypeProperty , owl:FunctionalProperty ; + rdfs:domain :ChunkReference ; + rdfs:range xsd:string ; + rdfs:comment "Value of the PREFIX environment variable in the build environment (defaults to /usr)" . + +# FIXME: it's possible to specify in OWL that 'bootstrap' and 'normal' are the +# only valid values. +:buildMode a owl:DatatypeProperty , owl:FunctionalProperty ; + rdfs:domain :ChunkReference ; + rdfs:range xsd:string . + + +## Chunk-specific properties + +# build-system isn't included here, as it overlaps with the *-commands +# fields in an unfortunate way. + +# Note that representing lists of things in RDF is a bit of a pain. +# http://smiy.sourceforge.net/olo/spec/orderedlistontology.html might +# be worth investigating. + +:producesChunkArtifact a owl:ObjectProperty , rdf:Seq ; + rdfs:domain :Chunk ; + rdfs:range :ChunkArtifact ; + rdfs:comment "Describes how this artifact is split once built." . + +:maxJobs a owl:FunctionalProperty ; + rdfs:domain :Chunk ; + rdfs:range xsd:integer ; + rdfs:comment "Number of parallel jobs that can be run for this chunk. Only useful if set to 1, to mark components which have Makefiles that do not work with `make -j N`." + +:CommandSequence a owl:Class ; + rdfs:subClassOf rdf:Seq ; + rdfs:comment "An ordered sequence of commands." . + +:preConfigureCommands a owl:ObjectProperty , owl:FunctionalProperty ; + rdfs:domain :Chunk ; + rdfs:range :CommandSequence . + +:configureCommands a owl:ObjectProperty , owl:FunctionalProperty ; + rdfs:domain :Chunk ; + rdfs:range :CommandSequence . + +:postConfigureCommands a owl:ObjectProperty , owl:FunctionalProperty ; + rdfs:domain :Chunk ; + rdfs:range :CommandSequence . + +:preBuildCommands a owl:ObjectProperty , owl:FunctionalProperty ; + rdfs:domain :Chunk ; + rdfs:range :CommandSequence . + +:buildCommands a owl:ObjectProperty , owl:FunctionalProperty ; + rdfs:domain :Chunk ; + rdfs:range :CommandSequence . + +:postBuildCommands a owl:ObjectProperty , owl:FunctionalProperty ; + rdfs:domain :Chunk ; + rdfs:range :CommandSequence . + +:preInstallCommands a owl:ObjectProperty , owl:FunctionalProperty ; + rdfs:domain :Chunk ; + rdfs:range :CommandSequence . + +:installCommands a owl:ObjectProperty , owl:FunctionalProperty ; + rdfs:domain :Chunk ; + rdfs:range :CommandSequence . + +:postInstallCommands a owl:ObjectProperty , owl:FunctionalProperty ; + rdfs:domain :Chunk ; + rdfs:range :CommandSequence . + + +# Artifact properties + +:includes a owl:DatatypeProperty , rdf:Seq ; + rdfs:domain :Artifact ; + rdfs:range xsd:string ; + rdfs:comment "A regular expression pattern. The results of a build are matched against this pattern and any that match will be included in that artifact." . diff --git a/schemas/chunk.json-schema b/schemas/chunk.json-schema new file mode 100644 index 00000000..8de2fb5f --- /dev/null +++ b/schemas/chunk.json-schema @@ -0,0 +1,116 @@ +$schema: http://json-schema.org/draft-04/schema# +id: http://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/definitions.git/tree/schemas/chunk.json-schema + +description: | + This is a JSON-Schema description of a 'chunk' .morph file, which is part of + the Baserock definitions YAML representation format. + + This JSON-Schema file is valid for VERSION 7 of the Baserock definitions + YAML serialisation format. + + The Baserock definitions format is the recommended way of representing + Baserock definitions on disk. The actual data model is described separately. + See https://wiki.baserock.org/definitions for more information. + + This schema is represented as YAML, so that it can be edited more easily. + You may need to convert to JSON if using a JSON-Schema tool that expects + its input to be an actual string containing data serialised as JSON. + +definitions: + # Corresponds to CommandSequence in Baserock data model. + command-sequence: + type: array + items: { type: string } + + # Corresponds to DeviceNode in Baserock data model. + device-node: + type: object + required: [type, filename, gid, uid, major, minor, permissions] + properties: + type: { type: string } + filename: { type: string } + gid: { type: integer } + uid: { type: integer } + major: { type: integer } + minor: { type: integer } + permissions: { type: string } + + # Defines one or more instances of ChunkArtifact from the Baserock data model. + split-rules: + type: array + items: + type: object + + required: [artifact, include] + additionalProperties: false + + properties: + artifact: {type: string} + include: + type: array + items: + type: string + format: regex + + system-integration-commands: + type: object + patternProperties: + # The property name here should correspond to the name of the chunk's + # artifacts, probably the '-bins' artifact if you are using the normal + # splitting rules. + ^.*$: + type: object + patternProperties: + ^.*$: + $ref: "#/definitions/command-sequence" + +# Corresponds to Chunk in Baserock data model. +type: object + +additionalProperties: false +required: [ 'name', 'kind'] + +properties: + name: { type: string } + kind: { enum: [ "chunk" ] } + + description: { type: string } + + build-system: { type: string } + max-jobs: { type: integer } + + products: + $ref: "#/definitions/split-rules" + + pre-configure-commands: + $ref: "#/definitions/command-sequence" + configure-commands: + $ref: "#/definitions/command-sequence" + post-configure-commands: + $ref: "#/definitions/command-sequence" + pre-build-commands: + $ref: "#/definitions/command-sequence" + build-commands: + $ref: "#/definitions/command-sequence" + post-build-commands: + $ref: "#/definitions/command-sequence" + pre-install-commands: + $ref: "#/definitions/command-sequence" + install-commands: + $ref: "#/definitions/command-sequence" + post-install-commands: + $ref: "#/definitions/command-sequence" + pre-strip-commands: + $ref: "#/definitions/command-sequence" + strip-commands: + $ref: "#/definitions/command-sequence" + post-strip-commands: + $ref: "#/definitions/command-sequence" + + system-integration: + $ref: "#/definitions/system-integration-commands" + + devices: + type: array + items: + $ref: "#/definitions/device-node" diff --git a/schemas/cluster.json-schema b/schemas/cluster.json-schema new file mode 100644 index 00000000..1a628c7f --- /dev/null +++ b/schemas/cluster.json-schema @@ -0,0 +1,64 @@ +$schema: http://json-schema.org/draft-04/schema# +id: http://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/definitions.git/tree/schemas/cluster.json-schema + +description: + This is a JSON-Schema description of a 'cluster' .morph file, which is part + of the Baserock definitions YAML representation format. + + This JSON-Schema file is valid for VERSION 7 of the Baserock definitions + YAML serialisation format. + + The Baserock definitions format is the recommended way of representing + Baserock definitions on disk. The actual data model is described separately. + See https://wiki.baserock.org/definitions for more information. + + This schema is represented as YAML, so that it can be edited more easily. + You may need to convert to JSON if using a JSON-Schema tool that expects + its input to be an actual string containing data serialised as JSON. + +definitions: + # A reference to a System, plus one or more SystemDeployment for that system. + system-deployment-set: + type: object + + required: [ 'morph', 'deploy' ] + additionalProperties: false + + properties: + morph: { type: string } + deploy-defaults: + type: object + additionalProperties: true + deploy: + patternProperties: + ^.*$: { $ref: "#/definitions/system-deployment" } + subsystems: + type: array + items: { $ref: "#/definitions/system-deployment-set" } + + # Corresponds to SystemDeployment in Baserock data model. + system-deployment: + type: object + + required: [ 'type', 'location' ] + additionalProperties: true + + properties: + type: { type: string } + location: { type: string } + + +# Corresponds to Cluster in Baserock data model. +type: object + +#required: [ 'name', 'kind', 'systems' ] +additionalProperties: false + +properties: + name: { type: string } + kind: { enum: [ "cluster" ] } + description: { type: string } + + systems: + type: array + items: { $ref: "#/definitions/system-deployment-set" } diff --git a/schemas/stratum.json-schema b/schemas/stratum.json-schema new file mode 100644 index 00000000..0330f37d --- /dev/null +++ b/schemas/stratum.json-schema @@ -0,0 +1,99 @@ +$schema: http://json-schema.org/draft-04/schema# +id: http://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/definitions.git/tree/schemas/chunk.json-schema + +description: | + This is a JSON-Schema description of a 'stratum' .morph file, which is part + of the Baserock definitions YAML representation format. + + This JSON-Schema file is valid for VERSION 7 of the Baserock definitions + YAML serialisation format. + + The Baserock definitions format is the recommended way of representing + Baserock definitions on disk. The actual data model is described separately. + See https://wiki.baserock.org/definitions for more information. + + This schema is represented as YAML, so that it can be edited more easily. + You may need to convert to JSON if using a JSON-Schema tool that expects + its input to be an actual string containing data serialised as JSON. + +definitions: + # Defines one or more instances of StratumArtifact from the Baserock data + # model. + split-rules: + type: array + items: + type: object + + required: [artifact, include] + additionalProperties: false + + properties: + artifact: {type: string} + include: + type: array + items: + type: string + format: regex + + # Corresponds to ChunkReference in Baserock data model. + chunk-reference: + type: object + + required: [ 'repo', 'ref' ] + additionalProperties: false + + properties: + name: { type: string } + morph: { type: string } + repo: { type: string } + ref: { type: string } + unpetrify-ref: { type: string } + build-mode: { type: string } + prefix: { type: string } + build-system: { type: string } + build-depends: + type: array + items: { type: string } + artifacts: + type: object + # This defines which chunk artifacts go in which stratum artifact. + # E.g. "glibc-nss: build-essential-runtime" specifies the glibc-nss + # chunk artifact should go in the build-essential-runtime stratum + # artifact. + patternProperties: + ^.*$: { type: string } + + # This doesn't need any special treatment in the Baserock data model because + # it's a link to another stratum definition, without any extra info. + stratum-reference: + type: object + + required: [ 'morph' ] + additionalProperties: false + + properties: + morph: { type: string } + + +# Corresponds to Stratum in Baserock data model. +type: object + +required: [ 'name', 'kind', 'chunks' ] +additionalProperties: false + +properties: + name: { type: string } + kind: { enum: [ "stratum" ] } + description: { type: string } + + build-depends: + type: array + items: + $ref: "#/definitions/stratum-reference" + + products: + $ref: "#/definitions/split-rules" + + chunks: + type: array + items: { $ref: "#/definitions/chunk-reference" } diff --git a/schemas/system.json-schema b/schemas/system.json-schema new file mode 100644 index 00000000..a2fc0c5d --- /dev/null +++ b/schemas/system.json-schema @@ -0,0 +1,59 @@ +$schema: http://json-schema.org/draft-04/schema# +id: http://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/definitions.git/tree/schemas/system.json-schema + +description: | + This is a JSON-Schema description of a 'system' .morph file, which is part of + the Baserock definitions YAML representation format. + + This JSON-Schema file is valid for VERSION 7 of the Baserock definitions + YAML serialisation format. + + The Baserock definitions format is the recommended way of representing + Baserock definitions on disk. The actual data model is described separately. + See https://wiki.baserock.org/definitions for more information. + + This schema is represented as YAML, so that it can be edited more easily. + You may need to convert to JSON if using a JSON-Schema tool that expects + its input to be an actual string containing data serialised as JSON. + +definitions: + # In the Baserock data model, this becomes a list of links to StratumArtifact + # entities. + stratum-reference: + type: object + + required: [ 'morph' ] + additionalProperties: false + + properties: + name: { type: string } + morph: { type: string } + artifacts: + type: array + items: { type: string } + + +# Corresponds to System in Baserock data model. +system: +type: object + +required: [ 'name', 'kind', 'strata' ] +additionalProperties: false + +properties: + name: { type: string } + kind: { enum: [ "system" ] } + description: { type: string } + + # Morph and YBD will only accept certain values for 'arch' based on + # hardcoded conditions in those tools. + arch: { type: string } + + strata: + type: array + items: + $ref: "#/definitions/stratum-reference" + + configuration-extensions: + type: array + items: { type: string } diff --git a/scripts/yaml-jsonschema b/scripts/yaml-jsonschema new file mode 100755 index 00000000..64f52a79 --- /dev/null +++ b/scripts/yaml-jsonschema @@ -0,0 +1,50 @@ +#!/usr/bin/env python +# Copyright (C) 2015 Codethink Limited +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; version 2 of the License. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License along +# with this program. If not, see . + + +'''A tool to validate YAML files against the JSON-Schema schemas. + +This wraps Python `jsonschema` module so that YAML schemas can be understood +and YAML data can be validated. + +Usage: yaml-jsonschema SCHEMA INPUT1 [INPUT2, ...] + +''' + + +import jsonschema +import yaml + +import sys + + +schema_file = sys.argv[1] +input_files = sys.argv[2:] + + +with open(schema_file) as f: + schema = yaml.load(f) + + +for input_file in input_files: + with open(input_file) as f: + data = yaml.load(f) + + try: + jsonschema.validate(data, schema) + print("%s: valid" % input_file) + except jsonschema.ValidationError as e: + # Print 'e' instead of 'e.message' for more information! + print("%s: %s" % (input_file, e.message)) -- cgit v1.2.1