I'm not sure what the purpose of a JSON Schema "description" field is. Does the field serve as a space to comment? Does the field serve as an ID?
{
"id": "http://www.noodle.org/entry-schema#",
"schema": "http://json-schema.org/draft-04/schema#",
"description": "schema for online courses",
"type": "object",
"properties": {
"institution": {
"type": "object",
"$ref" : "#/definitions/institution"
},
"person": {
"type": "object",
"items": {
"type": "object",
"$ref": "#/definitions/person"
}
"definitions": {
"institution": {
"description": "University",
"type": "object",
"properties": {
"name":{"type":"string"},
"url":{
"format": "uri",
"type": "string"
},
"descriptionofinstitution":{"type":"string"},
"location": {
"description": "location",
"type": "string",
"required": true
}
}
}
According to the JSON-Schema specification (http://json-schema.org/latest/json-schema-validation.html#anchor98), the purpose of the "description" (and "title") fields is to decorate a user interface with information about the data produced by this user interface. A title will preferrably be short, whereas a description will provide explanation about the purpose of the instance described by this schema.
It is probably some additional explanation, in order to enhance the knowledge concerning the specific entry, if the id is not enough. Of course it doesn't affect the behavior of the code as code itself
Related
Lets say I have two schemas defined as follows -
ADDRESS_CLASS_SCHEMA_DEFINITION = {
"title": "Address",
"type": "object",
"properties": {
"country_code": {
"$ref": "#/definitions/CountryCode"
},
"city_code": {
"title": "City Code",
"type": "string"
},
"zipcode": {
"title": "Zipcode",
"type": "string"
},
"address_str": {
"title": "Address Str",
"type": "string"
}
},
"required": [
"country_code",
"city_code",
"zipcode"
],
"definitions": {
"CountryCode": {
"title": "CountryCode",
"description": "An enumeration.",
"enum": [
"CA",
"USA",
"UK"
],
"type": "string"
}
}
}
EMPLOYEE_CLASS_SCHEMA_DEFINITION = {
"title": "Employee",
"type": "object",
"properties": {
"id": {
"title": "Id",
"type": "integer"
},
"name": {
"title": "Name",
"type": "string"
},
"email": {
"title": "Email",
"type": "string"
},
"telephone": {
"title": "Telephone",
"type": "string"
},
"address": {
"$ref": "#/definitions/Address"
}
},
"required": [
"id",
"name",
"email"
],
"definitions": {
"Address": ADDRESS_CLASS_SCHEMA_DEFINITION
}
}
I'm trying to re-use sub-schema definitions by defining a constant and referencing them individually in definitions (for example address-schema is referenced through constant in employee-schema definition). This approach works for individual schemas, however there seems to be a json-pointer path issue for Employee schema - #/definitions/CountryCode wouldn't resolve in Employee schema. I was assuming that #/definitions/CountryCode would be a relative path on Address schema as its scope is defined on a sub-schema, but my understanding seems wrong. I can make it work by flattening out like below, however I donot want to take this route -
{
"title": "Employee",
"type": "object",
"properties": {
"id": {
"title": "Id",
"type": "integer"
},
"name": {
"title": "Name",
"type": "string"
},
"email": {
"title": "Email",
"type": "string"
},
"telephone": {
"title": "Telephone",
"type": "string"
},
"address": {
"$ref": "#/definitions/Address"
}
},
"required": [
"id",
"name",
"email"
],
"definitions": {
"CountryCode": {
"title": "CountryCode",
"description": "An enumeration.",
"enum": [
"CA",
"USA",
"UK"
],
"type": "string"
},
"Address": {
"title": "Address",
"type": "object",
"properties": {
"country_code": {
"$ref": "#/definitions/CountryCode"
},
"city_code": {
"title": "City Code",
"type": "string"
},
"zipcode": {
"title": "Zipcode",
"type": "string"
},
"address_str": {
"title": "Address Str",
"type": "string"
}
},
"required": [
"country_code",
"city_code",
"zipcode"
]
}
}
}
I'm wondering how to fix this, I've briefly looked into jsonschema-bundling and using $id but from best practices it seems like the general recommendation is to use $id when dealing with URI's alone. Would like to know about best practices and how to fix this problem, would also appreciate if someone can point me on how to use $id correctly (for example, constant based approach seems to work when I provide identifiers like $id: Address, $id: Employee). Thanks in advance.
JSON Schema implementations work in JSON land. When you combine your schemas in your example above, presumably in javascript/node.js, by the time it gets to the JSON Schema implementation for validation execution, any knowledge that there were separate schemas is lost. (It's generally not considered that this approach is the best approach.)
The EASY fix here SHOULD be just to define $id in each of the roots of your schemas. These should be a fully qualfied URI. It doesn't really matter what they are at this point. They could be https://example.com/a and https://example.com/b. Then, in the primary schema, you can do $ref: https://example.com/b.
Implementations should provide you with a way to load in your other/non-primary schemas so the $id values can be stored in an index. Using $id in your other schema with a fully qualified URI will signify a "resource boundary".
https://json-schema.hyperjump.io is the only web playground to support multiple files/schemas/"Schema Resources", so you can test this out there to confirm your expectations.
Not all implementations make it easy or even provide a means to import your other schemas, but they should.
If you have follow up questions, feel free to leave a comment, or join the JSON Schema slack server if it would be off-topic for StackOverflow.
I have a JSON schema that contains "$ref" tags and I am trying to get a version of the JSON schema that have the "$ref" tags resolved. I am only looking to resolve "$ref" from definition (tags) within the JSON Schema string (ie. not external resolution needed).
Is there a library that performs the resolution of the JSON Schema? (I am currently using org.everit.json.schema library, which is great, but I can't find how to do what I need).
For example, my original schema is:
{
"$id": "https://example.com/arrays.schema.json",
"description": "A representation of a person, company, organization, or place",
"title": "complex-schema",
"type": "object",
"properties": {
"fruits": {
"type": "array",
"items": {
"type": "string"
}
},
"vegetables": {
"type": "array",
"items": { "$ref": "#/$defs/veggie" }
}
},
"$defs": {
"veggie": {
"type": "object",
"required": [ "veggieName", "veggieLike" ],
"properties": {
"veggieName": {
"type": "string",
"description": "The name of the vegetable."
},
"veggieLike": {
"type": "boolean",
"description": "Do I like this vegetable?"
}
}
}
}
}
Which would resolve to something like this (notice that the "#defs/veggie" resolves to its definition inserted inline in the schema):
{
"$id": "https://example.com/arrays.schema.json",
"description": "A representation of a person, company, organization, or place",
"title": "complex-schema",
"type": "object",
"properties": {
"fruits": {
"type": "array",
"items": {
"type": "string"
}
},
"vegetables": {
"type": "array",
"items": {
"type": "object",
"required": [ "veggieName", "veggieLike" ],
"properties": {
"veggieName": {
"type": "string",
"description": "The name of the vegetable."
},
"veggieLike": {
"type": "boolean",
"description": "Do I like this vegetable?"
}
}
}
}
}
}
This isn't possible in the general sense, because:
the $ref might be recursive (i.e. reference itself again)
the keywords in the $ref might duplicate some of the keywords in the containing schema, which would cause some logic to be overwritten.
Why do you need to alter the schema in this way? Generally, a JSON Schema implementation will resolve the $refs automatically while evaluating the schema against provided data.
I want to do three things
Validate JSON against a JSON-Schema
Create JSON-Schema to AVRO Schema converter
Create JSON-Schema to Hive Table converter
The problem I'm facing is the Schema has a referencing chain.
I'm trying to use this JSON Schema Validator which resolves reference and validates but getting some errors at the moment.
But I haven't been able to find any library for the 2nd and the 3rd task.
And I have to create Nifi processors for these. I have done it for the first one.
One idea I have is to use an Inline Parser to deference the Schemas and create one big schema and use that for the tasks and hopefully, everything will work smoothly afterward.
Any suggestions on what is a good approach to tackle these issues.
One of the schemas is attached. Any help would be appreciated.
{
"id": "/schemas/bi/events/identification/carrier",
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Users Carrier Identified",
"description": "A successfully identified carrier of a user",
"type": "object",
"definitions": {
"carrier_identification_result": {
"type": "object",
"properties": {
"mno": {
"type": "string",
"title": "Mobile network operator",
"description": "The Mobile network operator",
"example": "Telekom"
},
"mvno": {
"type": "string",
"title": " Mobile virtual network operator",
"description": "The Mobile virtual network operator.",
"example": "Mobilcom-Debitel"
},
"mcc": {
"type": "string",
"title": "Mobile Country Code",
"description": "The Mobile Country Code as defined in the ITU-T Recommendation E.212",
"example": "262"
},
"mnc": {
"type": "string",
"title": "Mobile Network Code",
"description": "The Mobile Network Code as defined in the ITU-T Recommendation E.212",
"example": "01"
},
"country": {
"type": "string",
"title": "The code ISO 3166-1 alpha 2 for the country",
"example": "DE"
}
},
"required": [
"mno",
"country"
]
}
},
"allOf": [
{
"$ref": "../identification_service.json"
},
{
"properties": {
"type": {
"constant": "identification.carrier",
"example": "identification.carrier"
},
"event_data": {
"allOf": [
{
"$ref": "../identification_service.json#/definitions/event_data"
},
{
"type": "object",
"properties": {
"result": {
"$ref": "#/definitions/carrier_identification_result"
},
"required": [
"result"
]
}
}
]
}
}
}
]
}
Can I have a custom specifier/attribute like "required" keyword to decorate my Json schema fields with custom specifications.
Like for example:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Product",
"description": "A product from Acme's catalog",
"type": "object",
"properties": {
"id": {
"description": "The unique identifier for a product",
"type": "integer"
},
"name": {
"description": "Name of the product",
"type": "string"
},
"price": {
"type": "number",
"minimum": 0,
"exclusiveMinimum": true
},
"**credit-card**": {
"**type**": "**number**",
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"uniqueItems": true
}
},
"required": ["id", "name", "price"],
"**confidential**" : ["**credit-card**"]
}
Can I have a special keyword called "confidential" to make sure that "credit-card" should not be revealed and/or masked? Does the schema standards allow for such custom metadata keywords?
It depends on the library you will use to execute the validation. I've used AJV, it allows you to define custom keywords, you can find more information about it here.
JSON-schema says that a JSON document can declare the schema to which the document conforms using the $schema property. Example:
{
"$schema": "http://example.com/example_fancy_schema#",
"example_fancy_property": "cute fluffy kittens"
}
where the schema looks like:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Example Fancy Schema",
"description": "The schema that describes the example format.",
"type": "object",
"properties": {
"example_fancy_property": {
"type": "string",
"enum": ["cute fluffy kittens"]
}
},
"additionalProperties": false,
"required": [ "example_fancy_property" ]
}
Does this mean that one should add a property for this in the actual schema, e.g.:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Example Fancy Schema",
"description": "The schema that describes the example format.",
"type": "object",
"properties": {
"$schema": {
"type": "string",
"enum": ["http://example.com/example_fancy_schema#"]
},
"example_fancy_property": {
"type": "string",
"enum": ["cute fluffy kittens"]
}
},
"additionalProperties": false,
"required": [ "$schema", "example_fancy_property" ]
}
None of the examples on the JSON-schema website appear to declare this, so I suspect one isn't supposed to declare it. But I'm curious anyway :)
The $schema keyword is recommended for use in JSON Schemas, to denote the version of the schema standard being used.
However, it has no special meaning in data. Over HTTP, there are recommended ways to associate data with a schema, but the $schema property is not one of them.