I have an sample json:
{
"type": "persons",
"id": 2,
"attributes": {
"first": "something",
"second": "something else"
}
}
And I have to make a schema for it (using JSON API specs and JSON schema docs):
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"type": {
"type": "string",
"pattern": "^persons$"
},
"id": {
"type": "integer"
},
"attributes": {
"type": "object",
"properties": {...}
}
},
"required": ["type", "id", "attributes"]
}
And the question is: if the only acceptable value for "type" is "persons", should I use in schema pattern (like above) or enum like
"enum": ["persons"]
I couldn't get any clear answer from documentation, although in examples in specs enums are used for single values. So what's your opinion?
Ultimately, it doesn't really matter. Both will work and both are reasonable. That said, the most common approach I've seen is to use enum. Neither are perfect for readability, but I think enum is better for two reasons.
Using pattern requires two lines to express. Using enum requires only one because type is implied by the value in the array. Two lines are harder to read than one, so if that line is expressive enough, I say stick with one.
Not everyone is comfortable reading regex. enum might be more accessible for that reason.
Since draft-6 there is a new keyword called const for this use-case.
"type": {
"type": "string",
"const": "persons"
},
http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.1.3
Related
I have a a number of objects which share a common set of features but differ in one or more properties. The common content is specified as media content in the definitions. I have provided one such object with a 'format' property, but there are other objects, omitted to keep it short, that also have additional properties. Here is a snippet of my attempt at constructing the schema. Is this the correct way to accomplish, this? Many thanks
"definitions": {
"media-content":{
"type": "object",
"title": {
"type": "string"
},
"related-media": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
},
"type": "object",
"properties": {
"type": {
"format": "string",
"enum":["audio", "video"]
},
"category": {
"$ref": "#/definitions/media-content"
}
}
Is this the way to do it?
The first thing that stands out to me is that this isn't valid JSON Schema.
The title keyword provides a title for the schema so it expects a string, but because you've provided a schema, it looks like you're wanting it to be a property. Similarly related-media looks like you expect this to be a property. Are you missing wrapping these in a properties keyword, like you have later for type and category?
These changes would make media-content look like this:
"media-content":{
"type": "object",
"properties": {
"title": {
"type": "string"
},
"related-media": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
}
I have provided one such object with a 'format' property
Again, here, I'm not sure what you're getting at.
"properties": {
"type": {
"format": "string",
"enum":["audio", "video"]
},
"category": {
"$ref": "#/definitions/media-content"
}
}
This says you're expecting type to be a property in your object, but format isn't used right. Although the format keyword has some predefined types and does accept custom values, the way you're using it look like you really want to be using the type keyword. In the end, it doesn't matter because enum will restrict the value to the items you declare in the array ("audio" or "video").
It might be easier to see what you're trying to do if you posted a full minimum exaple.
That said, I'll try to build one to answer the question I think you're asking.
It sounds like you're wanting to build a polymorphic relationship: an inheritance hierarchy where a base type defines some properties and a number of derived types define additional properties.
There's not really a good way to do that with JSON Schema because JSON Schema is a constraints system. That is, you start with {} where anything is valid, and by adding keywords, you're reducing the number of values that are valid.
Still, you might be able to achieve something close by using allOf and $ref.
First, declare the base property set in its own schema. I'd separate them into independent schemas for easier handling. You also need to give it an $id.
{
"$id": "/base-type"
"type": "object",
"properties": {
"base-prop-1": { "type": "string" },
"base-prop-2": { "type": "number" }
}
}
Next, for each of your "derived" schemas, you'll want to create a new schema, each with their own $id value, that references the base schema and declares its own additional requirements.
{
"$id": "/derived-type-1",
"allOf": [
{ "$ref": "/base-type" },
{
"properties": {
"derived-prop": { "type": "boolean" }
}
}
]
}
This second schema requires everything from the /base-type and also requires a derived-prop property that holds a boolean value.
I have the following use-case I try to solve with JSON schemas.
I have a generic JSON data schema for, for example, a user. Here is an example of the user.schema.json file.
{
"type": "object",
"definitions": {},
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"email": {
"type": "string",
"minLength": 1
},
"locale": {
"type": "string",
"minLength": 1
},
"active": {
"type": "boolean",
"default": true
},
"password": {
"type": "string",
"minLength": 8
},
"roles": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
}
}
Now I have 2 different kinds of requests:
- POST: Add a user
- PATCH: Update user data.
In 1 case, I can send this data structure, with 3 required fields, while in case of a patch each field is optional.
So I get the post request file: post-user.schema.json:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$ref": "user.schema.json",
"required": [
"name",
"password",
"email"
]
}
And for my patch (path-user.schema.json:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$ref": "user.schema.json"
}
Now the issue that I am having is that my POST schema also marks a user like:
{
"name": "NoPassword",
"email": "nopassword#moba.nl",
"roles": []
}
Which is missing the required password field, as a valid JSON schema.
Apparently, this is not the way to assign required fields to a referenced data structure. I have tried to use google to see what I can find on the subject regarding this using searches like:
[ how to assign required field to referenced schema's ]
and I tried to obtain this info from the documentation.
I have no luck.
My questions now are:
A. Is it possible to assign required fields to a $referenced json schema data object.
B. If this is possible how to do it
C. If this is not possible, what would be a good way to approach this.
Any help is much appreciated.
Using $ref results in all other properties in the object being ignored, so you need to wrap your use of $ref.
Let's take a look at the spec:
An object schema with a "$ref" property MUST be interpreted as a
"$ref" reference. The value of the "$ref" property MUST be a URI
Reference. Resolved against the current URI base, it identifies the
URI of a schema to use. All other properties in a "$ref" object MUST
be ignored.
https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-01#section-8.3
Then consider the schema you included in your question:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$ref": "user.schema.json",
"required": [
"name",
"password",
"email"
]
}
Reading the spec, you can see why required will be ignored.
Originally $ref was only designed to replace a WHOLE object, not ADD to the conditions for the object.
What you want is for multiple schemas to be applied to the instance. To do this, you use allOf.
{
"$schema": "http://json-schema.org/draft-07/schema#",
"allOf": [
{
"$ref": "user.schema.json"
},
{
"required": [
"name",
"password",
"email"
]
}
]
}
I loaded this schema into a demo for you to test at https://jsonschema.dev - although it doesn't support references yet, so I transcluded the reference, but the validation will work the same.
From draft-8 onwards, $ref will behave as you expect, as it becomes an applicator keyword rather than a keyword with special behaviours, meaning other keywords in the same object will not need to be ignored.
Im trying to make a system monitor, which is highly customisable by user. This customization is achieved by using JSON file for modeling look of system monitor. The JSON could look like this.
{
"_": "WINDOW",
"name": "myWindow",
"children": [
{
"_": "CPU",
"name": "cpuMonitor",
"freq_Unit": "MHZ"
},
{
"_": "NETWORK",
"name": "network",
"unit": "Kb/s"
},
{
"_": "DISK",
"name": "disk"
}
],
"background": "red"
}
As you can see, each object coresponds to this schema.
{
"$schema": "http://json-schema.org/draft-07/schema#",
"name":"Component",
"type": "object",
"properties":{
"_": {
"type": "string"
},
"name":{
"type":"string"
},
"childern":{
"type":"array"
}
},
"required": ["_","name"]
}
But each component has also its own schema definition. I'd like to parse whole JSON and validate each node for different schema (first if its component and then to its corresponding schema).
I had look at rapidJson and other libraries, but I didnt find solution for validating nodes for different schema. Do you know any library which could do that? Or is it even possible to validate JSON in this way?
All feedback on how to solve this will be appreciated.
Edit: Corrected schema :(
There's a simple approach involved with that, use the oneOf pattern declaration to specify the layout of the array elements. Inside these nested declarations, you specify the fixed identifier (probably the content of your _ field) as a constant, so that there is only one nested schema matching each of your panel types.
Notes:
I had to specify the constant type identifier using the enum specifier because the regular constant specifier didn't work with the library I was using. This may also have been an oversight in the revision of the specification that it was based on.
A different approach is to split the the validation steps. You simply verify that the elements of the array are objects and that they have a string field _ containing one of the supported types. When iterating over the array, you then validate each field individually according to its _ field.
In addition to Ulrich's answer, here's an example of what I'd do:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Component",
"type": "object",
"definitions": {
"base": {
"properties": {
"name": { "type": "string" },
"children": {
"type": "array",
"items": { "$ref": "#" }
}
},
"required": [ "_", "name" ]
},
"cpu": {
"properties": {
"_": { "const": "CPU" },
"freq_Unit": "MHZ"
}
},
"network": {
"properties": {
"_": { "const": "NETWORK" },
"unit": "Kb/s"
}
},
"disk": {
"properties": {
"_": { "const": "DISK" }
}
},
"window": {
"properties": {
"_": { "const": "WINDOW" },
"background": { "enum": [ "red", "orange", "yellow", ... ] }
}
}
},
"allOf": [
{ "$ref": "#/definitions/base" },
{
"oneOf": [
{ "$ref": "#/definitions/cpu" },
{ "$ref": "#/definitions/network" },
{ "$ref": "#/definitions/disk" },
{ "$ref": "#/definitions/window" }
]
}
]
}
First, we require that any instance MUST adhere to base which declares _ and name as required properties. Additionally, we declare a children array property that requires all items also match this schema (giving us a recursive behavior). This doesn't really do much except that it allows us to declare these things in one place instead of having to declare them in the other three definitions.
(Note that we don't declare _ in the properties list. This means that any value will pass for this portion of the schema. We clean it up in the next part. If you want to ensure that future components are declared with strings, then you can add a "type": "string" requirement to that property, but I don't feel it's necessary unless others are authoring those components.)
Second, we declare each of our specific types as separate definitions, using the const keyword to isolate the one we want. This construct is analogous to a switch (or case) statement. If the instance doesn't match one of these explicit options, it fails. If it's missing one of the required base properties, it fails.
This will get you where you want to be.
To take it further, there are two more things you can do:
Add required to the other definitions to say that the specific properties are also required (e.g. freq_Unit for the cpu definition).
Declare each of the definitions in separate files. This would allow you to add a new definition by simply adding a new file and referencing it in the main schema. In my opinion, it's a bit cleaner. Some people prefer to have it all in one file, though.
I have spent all day trying to get this to work, will post a list of references and things I have tried after the question.
So here is my jsonschema:
{
"data": [{
"required": "effort",
"decisive": "maybe",
"field1": 7
},
{
"required": "effort",
"decisive": "no",
"field1": 6
}],
"schema": {
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"items": {
"type": "object",
"properties": {
"field1": {
"type": "string",
"pattern": "[A-Z]",
"title": "field1"
},
"required": {
"type": "string",
"title": "required",
"readonly": true
},
"decisive": {
"type": "string",
"title": "Decisive",
"enum": ["yes", "no", "maybe", "not now"]
}
}
}
}
}
Consider the exact piece of jsonschema but with the field1 element as follows:
"field1": {
"type": "integer",
"minimum": 5,
"maximum": 10,
"title": "field1"
}
The first example validates only capital letters in its field1
The second wants an integer between 5 and 10.
How can you make it validate either of these, so both are accepted -
either only capital letters
or an integer between 5 and 10?
Oh - the field1 in the data section above is not that important, it is a desired default value.
I have tried all kinds of ideas -
with oneOf - here, here, here
param - here
additionalProperties - here
required - here
The intuitive thing was to use the oneOf on pattern, but oneOf, as is mentioned in many questions, does not do anything inside the properties section, only outside it. So I tried to have the exact same properties inside a oneOf with just the one difference as described above. That did not work either, and contains a lot of repetition which must somehow be avoidable.
Does anyone know how to solve this? Am out of ideas..
You were one the right track with oneOf, except what you actually want is anyOf. Almost every time you think you want oneOf, you really want anyOf. Remember that the values of properties are schemas just like any other. You can use the boolean keywords there just like anywhere else.
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"items": {
"type": "object",
"properties": {
"field1": {
"title": "field1"
"anyOf": [
{
"type": "string",
"pattern": "[A-Z]"
},
{
"type": "integer",
"minimum": 5,
"maximum": 10
}
]
},
"required": {
"type": "string",
"title": "required",
"readonly": true
},
"decisive": {
"type": "string",
"title": "Decisive",
"enum": ["yes", "no", "maybe", "not now"]
}
}
}
}
Edit 1
When you hear that oneOf can't be used inside properties, this is the kind of thing they are talking about.
{
"type": "object",
"properties": {
"anyOf": [
{
"field1": { ... }
},
{
"field1": { ... }
}
],
"required": { ... },
"decisive": { ... }
}
}
Edit 2
Because it came up in the comments, here's a better explanation of why oneOf is almost never the right choice. To be clear, oneOf will always work in place of anyOf. If anyOf didn't exist, JSON Schema wouldn't loose any expressive power.
However, anyOf is a more precise tool. Using oneOf when anyOf will do is like using a sledge hammer to drive a nail when you have a simple claw hammer in your toolbox.
anyOf is the boolean OR operation. oneOf is the boolean "exclusive OR" (XOR) operation. "XOR" has so little usefulness, that modern languages don't even have support for it. OR is usually represented with the operator ||. XOR has no analog.
anyOf means any of the items can be true. oneOf means one and only one of the items can be true. When you use oneOf, the validator needs to test all of the schemas to ensure that one schema validates as true and the rest validate as false. When you use anyOf, the validator can stop as soon as it finds a schema that validates as true. This is called "short circuiting" and all modern programming languages do this when evaluating OR operations. When the schemas are mutually exclusive (which they almost always are), continuing to validate schemas after one is found is pure waste and therefore should be avoided.
I think oneOf is overused because from a natural language perspective, it sounds right.
I have a json schema which describes a fairly complex API querying syntax. A few of the properties are pattern matched but also need to accept other values (i.e. other explicit strings) other than just the pattern. I can't seem to find anywhere in the multitude of json schema sites any examples of this.
An example:
{
"type": "object",
"properties": {
"$gte": {
"type": "string",
"pattern": "<some-pattern>"
}
}
}
What i'd like to be able to do in the example above is specify that $gte can be any of a certain set of constrained values. For example, this specific implementation requires that "$gte"'s values be constrained to one of the following:
A specific date format
A token {token} which gets replaced with a special value on the server-side
I've seen the oneOf property used in this situation but only with the format property so I'm assuming that this is possible, just not sure of the syntax of how to implement it, for instance it could be something like this:
{
"type": "object",
"properties": {
"$gte": {
"type": "string",
"oneOf": [
{"pattern": "<some-pattern>"},
"{token}",
"{another_token}"
]
}
}
}
Any clarity on how to accomplish this would be greatly appreciated as I'm not having much luck with the specification Draft 4 for json schema or in finding any examples.
If you want data to be one of a fixed set of exact values, you can use enum:
{
"type": "string",
"enum": ["stop", "go"]
}
So, to fit this in your example, try:
{
"type": "object",
"properties": {
"$gte": {
"type": "string",
"oneOf": [
{"pattern": "<some-pattern>"},
{"enum": ["TOKEN", "ANOTHER_TOKEN"]}
]
}
}
}
In addition to what already said, for the date you can use "date" within the "oneOf"
https://json-schema.org/understanding-json-schema/reference/string.html#dates-and-times