Commit 8b65088f authored by Rafael Monnerat's avatar Rafael Monnerat

wip for json schema

parent 6f3454ce
Instance descriptors
====================
.. contents::
Abstract
--------
Instances generated from software release take parameters (typically to
customise instantiation and instance behaviour) and publish results
(typically allowing access to requester). This also applies not only to
the root software instance, but to any instance requested by another
instance.
The structure of these values is constrained by how the Software Release
was implemented, and must be documented so it can be used. Instance
descriptors are intended to provide such documentation in a form
allowing automated generation of a user interface to consult and provide
parameters, and to consult published results.
Specification
-------------
Instance parameters (=requests) and published results (=responses) are
specified using json schemas, as defined in the following resources:
- http://tools.ietf.org/html/draft-zyp-json-schema-03#section-5.20
- http://tools.ietf.org/html/draft-zyp-json-schema-04
- http://json-schema.org/
These schema MUST ignore any technical overhead, such as
serialisation-format-imposed layers (such as
``<?xml ...?><instance></instance>`` level in ``xml`` serialisation,
or the ``<prameter id="_">`` level in ``json-in-xml`` serialisation).
Rules to define access to request & response schemas for a given
software release and software type should be provided in a file whose
name is deduced from the software release URL by appending ".json" to
its path component. Components preceding path (scheme & netloc) MUST
be preserved, components succeeding path (query & fragment) SHOULD be
preserved. If a file actually resides at such URL, it MUST be valid
json syntax and satisfy the following json schema::
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Slapos Software Release instantiation descriptor",
"additionalProperties": false,
"properties": {
"name": {
"description": "A short human-friendly name for the sofware release",
"type": "string"
},
"description": {
"description": "A short description of the sofware release",
"type": "string"
},
"serialisation": {
"description": "How the parameters and results are serialised",
"required": true,
"enum": ["xml", "json-in-xml"],
"type": "string"
},
"software-type": {
"description": "Existing software types",
"required": true,
"patternProperties": {
".*": {
"description": "Software type declaration",
"additionalProperties": false,
"properties": {
"description": {
"description": "A human-friendly description of the software type",
"type": "string"
},
"serialisation": {
"description": "How the parameters and results are serialised, if different from global setting",
"enum": ["xml", "json-in-xml"],
"type": "string"
},
"request": {
"required": true,
"description": "URL, relative to Software Release base path, of a json schema for values expected by instance of current software type",
"type": "string"
},
"response": {
"required": true,
"description": "URL, relative to Software Release base path, of a json schema for values published by instance of current software type",
"type": "string"
},
"index": {
"description": "Value to use instead of software type id to sort them (in order to display most relevant software types earlier in a list, for example)",
"type": "any"
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
Error handling
--------------
If instantiation descriptor does not exist, is not valid json or does
not conform to this schema, it is ignored and a fall-back
representation is used. Likewise, if a software type of an existing
instance is not defined in software-type object or referenced schema
does not exist or is invalid, the same fall-back representation is used
for considered software type.
A fall-back representation must allow full control to the user, without
any guided editing: user is expected to serialise on his own and
provides & receives raw strings as request and responses, respectively.
Request schemas, when present and valid, MAY be used to validate user
input.
It SHOULD be made possible for user to violate the schema just as it is
possible for existing instances to already violate schemas. These
violation should be represented in a way which makes as much sense as
possible: displaying recursively all object properties and iteratively
all list items with as appropriate as possible fields, with a fall-back
on free text input. These extra fields generated from existing data or
created on-the-fly by the user MUST NOT prevent schema-conforming
fields from being displayed and functional.
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Slapos Software Release instantiation descriptor",
"additionalProperties": false,
"properties": {
"name": {
"description": "A short human-friendly name for the sofware release",
"type": "string"
},
"description": {
"description": "A short description of the sofware release",
"type": "string"
},
"serialisation": {
"description": "How the parameters and results are serialised",
"required": true,
"enum": ["xml", "json-in-xml"],
"type": "string"
},
"software-type": {
"description": "Existing software types",
"required": true,
"patternProperties": {
".*": {
"description": "Software type declaration",
"additionalProperties": false,
"properties": {
"description": {
"description": "A human-friendly description of the software type",
"type": "string"
},
"serialisation": {
"description": "How the parameters and results are serialised, if different from global setting",
"enum": ["xml", "json-in-xml"],
"type": "string"
},
"request": {
"required": true,
"description": "URL, relative to Software Release base path, of a json schema for values expected by instance of current software type",
"type": "string"
},
"response": {
"required": true,
"description": "URL, relative to Software Release base path, of a json schema for values published by instance of current software type",
"type": "string"
},
"index": {
"description": "Value to use instead of software type id to sort them (in order to display most relevant software types earlier in a list, for example)",
"type": "any"
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Slapos Software Release instantiation descriptor",
"additionalProperties": false,
"properties": {
"instance_guid": {
"description": "XXX",
"type": "string"
},
"computer_guid": {
"description": "XXX",
"type": "string"
}
}
}
\ No newline at end of file
...@@ -2,87 +2,100 @@ ...@@ -2,87 +2,100 @@
"$schema": "http://json-schema.org/draft-04/schema#", "$schema": "http://json-schema.org/draft-04/schema#",
"properties": { "properties": {
"user-authorized-key": { "user-authorized-key": {
"description" : "SSH public key in order to connect to the SSH server of this runner instance", "title": "User Authorized Key",
"type": "string" "description": "SSH public key in order to connect to the SSH server of this runner instance.",
"type": "string",
}, },
"instance-amount": { "instance-amount": {
"description": "number of slappart to deploy inside the runner. Needs instance to be restarted.", "title": "Partition Amount",
"description": "Number of slappart to deploy inside the runner (default is 10). Needs instance to be restarted.",
"type": "integer", "type": "integer",
"default": 10 "minimum": 1,
"maximum": 40,
}, },
"slapos-software": { "slapos-software": {
"title": "Pre-selected Software Release",
"description": "a relative path from the slapos git repo to a folder containing a software release, which will be automaticaly deployed while the runner instanciation, and only if the parameter auto-deploy is set to 'true'. For example: 'software/helloworld", "description": "a relative path from the slapos git repo to a folder containing a software release, which will be automaticaly deployed while the runner instanciation, and only if the parameter auto-deploy is set to 'true'. For example: 'software/helloworld",
"type": "string" "type": "string",
}, },
"auto-deploy": { "description": "authorizes the software declared with 'slapos-software' to be automatically deployed, or not. Needs instance to be restarted.", "auto-deploy": {
"title": "Automatically Deploy Software",
"description": "Authorizes the software declared with 'slapos-software' to be automatically deployed, or not. Needs instance to be restarted. (default is false)",
"type": "boolean", "type": "boolean",
"default": "false"
}, },
"slapos-repository": { "slapos-repository": {
"description": "url of the default git repository that will be download by the runner while its instanciation. Will be cloned in a directory named 'slapos'", "title": "SlapOS Git Repository URL",
"description": "url of the default git repository that will be download by the runner while its instanciation. Will be cloned in a directory named 'slapos' (default is http://git.erp5.org/repos/slapos.git)",
"type": "string", "type": "string",
"default": "http://git.erp5.org/repos/slapos.git" "format": "uri",
"pattern": "^(http|https|ftp)://",
}, },
"slapos-reference": { "slapos-reference": {
"description": "commit reference on which the default repository will checkout", "title": "SlapOS Git Branch Name",
"description": "Branch or hash on which the default repository will checkout (default is master)",
"type": "string", "type": "string",
"default": "master"
}, },
"auto-deploy-instance": { "auto-deploy-instance": {
"description": "prevent the runner from deploying and starting instances. Needs instance to be restarted.", "title": "Automatically Deploy Instances",
"description": "Prevent the runner from deploying and starting instances. Needs instance to be restarted. It is set to false for instances of type 'import' in resiliency in any case (default is false)",
"type": "boolean", "type": "boolean",
"default": "true, but is set to false for instances of type 'import' in resiliency"
}, },
"autorun": { "autorun": {
"description": "let automaticaly build and run a declared software with 'slapos-software'. Only works if 'slapos-software' is set, and 'auto-deploy' is true. Needs instance to be restarted.", "title": "Automatically Run Sofware/Instance",
"description": "Let automaticaly build and run a declared software with 'slapos-software'. Only works if 'slapos-software' is set, and 'auto-deploy' is true. Needs instance to be restarted. (default is false)",
"type": "boolean", "type": "boolean",
"default": "false"
}, },
"slapos-software-type": { "slapos-software-type": {
"title": "Deployed Instance Software Type" ,
"description": "Software type of your instance inside the runner", "description": "Software type of your instance inside the runner",
"type": "string" "type": "string",
},
"parameter-*": {
"description": "'*' is a parameter which will be used to configure the instance inside the runner.",
"type": "string"
}, },
"custom-frontend-backend-url": { "custom-frontend-backend-url": {
"title": "Custom Frontend Backend URL",
"description": "return an ipv4 frontend of the given ipv6(+optional port)", "description": "return an ipv4 frontend of the given ipv6(+optional port)",
"type": "string" "type": "string",
"format": "uri",
}, },
"custom-frontend-backend-type": { "custom-frontend-backend-type": {
"title": "Custom Frontend Backend Type",
"description": "The type of the frontend slave instance to ask", "description": "The type of the frontend slave instance to ask",
"type": "string" "type": "string",
"enum": ["zope"],
}, },
"custom-frontend-basic-auth": { "custom-frontend-basic-auth": {
"title": "Custom Frontend Basic Auth",
"description": "if the ip given with 'custom-frontend-backend-url' is secure, set it to true for the promise do not fail", "description": "if the ip given with 'custom-frontend-backend-url' is secure, set it to true for the promise do not fail",
"type": "boolean", "type": "boolean",
"default": "false"
}, },
"custom-frontend-instance-guid": { "custom-frontend-instance-guid": {
"title": "Custom Frontend Instance GUID",
"description": "Instance guid of the frontend you whish to use", "description": "Instance guid of the frontend you whish to use",
"type": "string", "type": "string",
"default": "none"
}, },
"custom-frontend-software-type": { "custom-frontend-software-type": {
"description": "SoftwareType of the frontend you request", "title": "Custom Frontend Software Type",
"default": "RootSoftwareInstance", "description": "SoftwareType of the frontend you request (default is RootSoftwareInstance)",
"type": "string" "type": "string",
"enum": ["RootSoftwareInstance", "default"],
}, },
"custom-frontend-software-url": { "custom-frontend-software-url": {
"description": "Software Url of the frontend you request", "title": "Custom Frontend Software URL",
"default": "http://git.erp5.org/gitweb/slapos.git/blob_plain/HEAD:/software/apache-frontend/software.cfg", "description": "Software Url of the frontend you request (ie.: http://git.erp5.org/gitweb/slapos.git/blob_plain/HEAD:/software/apache-frontend/software.cfg)",
"type": "string" "type": "string",
"format": "uri",
}, },
"monitor-port": { "monitor-port": {
"description": "allow to manually change the port on wich the apache server running monitoring interface is listening. The default value for the webrunner is different from the default value of the standalone stack-monitor server", "title": "Monitor Port",
"description": "Allow to manually change the port on wich the apache server running monitoring interface is listening. The default value for the webrunner is different from the default value of the standalone stack-monitor server (default 9684)",
"type": "integer", "type": "integer",
"default": 9684 "minimum": 9683,
"exclusiveMinimum": true,
}, },
"resilient-clone-number": { "resilient-clone-number": {
"description": "is the number of clones to be deployed when a resilient runner is ordered. Its value can be 1 or 2", "title": "Number of Resilient Clones",
"description": "Number of clones to be deployed when a resilient runner, if missing a single clone is provided. Its value can be 1 or 2",
"type": "integer", "type": "integer",
"default" : 1 "enum": [1, 2],
} }
} }
} }
{
"name": "Web Runner",
"description": "Web Runner",
"serialisation": "xml",
"software-type": {
"default": {
"title": "Default",
"description": "Standalone Runner",
"request": "instance-runner-input-schema.json",
"response": "instance-runner-output-schema.json",
"index": 0
},
"resilient": {
"title": "Resilient"
"description": "Resilient Runner",
"request": "instance-runner-resilient-input-schema.json",
"response": "instance-runner-output-schema.json",
"index": 1
}
}
}
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment