After the Schema Registry is deployed you will have access to its API endpoint. To register a schema, you have to send a POST request to the endpoint http://schema-registry-svc:8080/schemas in whose body you need to provide the name of the schema, description, schema_type, specification (the schema), compatibility and validity mode.

The compatibility type determines how the Schema Registry compares the new schema with previous versions of a schema, for a given subject. The Dataphos Schema Registry default compatibility type is BACKWARD. All the compatibility types are described in more detail in the sections below.

The validity type determines how strict the Schema Registry will be when registering a schema. Meaning, will it demand that the schema is compliant with the rules of the data format or with the schema rules. The Dataphos Schema Registry default validity type is FULL. Possible values for the validity mode are: FULL, NONE, SYNTAX_ONLY.

{
    "description": "new json schema for testing", 
    "schema_type": "json", 
    "specification":  "{\r\n  \"$id\": \"https://example.com/person.schema.json\",\r\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\r\n  \"title\": \"Person\",\r\n  \"type\": \"object\",\r\n  \"properties\": {\r\n    \"firstName\": {\r\n      \"type\": \"string\",\r\n      \"description\": \"The person's first name.\"\r\n    },\r\n    \"lastName\": {\r\n      \"type\": \"string\",\r\n      \"description\": \"The person's last name.\"\r\n    },\r\n    \"age\": {\r\n      \"description\": \"Age in years which must be equal to or greater than zero.\",\r\n      \"type\": \"integer\",\r\n      \"minimum\": 0\r\n    }\r\n  }\r\n}\r\n",
    "name": "schema json",
    "compatibility_mode": "BACKWARD",
    "validity_mode": "FULL"
}

Using curl:

curl -XPOST -H "Content-type: application/json" -d '{
    "description": "new json schema for testing", 
    "schema_type": "json", 
    "specification":  "{\r\n  \"$id\": \"https://example.com/person.schema.json\",\r\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\r\n  \"title\": \"Person\",\r\n  \"type\": \"object\",\r\n  \"properties\": {\r\n    \"firstName\": {\r\n      \"type\": \"string\",\r\n      \"description\": \"The person's first name.\"\r\n    },\r\n    \"lastName\": {\r\n      \"type\": \"string\",\r\n      \"description\": \"The person's last name.\"\r\n    },\r\n    \"age\": {\r\n      \"description\": \"Age in years which must be equal to or greater than zero.\",\r\n      \"type\": \"integer\",\r\n      \"minimum\": 0\r\n    }\r\n  }\r\n}\r\n",
    "name": "schema json",
    "compatibility_mode": "BACKWARD",
    "validity_mode": "FULL"
}' 'http://schema-registry-svc:8080/schemas/'

The response to the schema registration request will be:

• STATUS 201 Created

  {
      "identification": "32",
      "version": "1",
      "message": "schema successfully created"
  }
  

• STATUS 409 Conflict -> indicating that the schema already exists

  {
      "identification": "32",
      "version": "1",
      "message": "schema already exists at id=32"
  }
  

• STATUS 500 Internal Server Error -> indicating a server error, which means that either the request is not correct ( missing fields) or that the server is down.

  {
      "message": "Internal Server Error"
  }
  

After the Schema Registry is registered you can update it by registering a new version under that schema ID. To update a schema, you have to send a PUT request to the endpoint http://schema-registry-svc:8080/schemas/<schema_ID> in whose body you need to provide the description (optional) of the version and the specification (the schema)

{
    "description": "added field for middle name",
    "specification": "{\r\n  \"$id\": \"https://example.com/person.schema.json\",\r\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\r\n  \"title\": \"Person\",\r\n  \"type\": \"object\",\r\n  \"properties\": {\r\n    \"firstName\": {\r\n      \"type\": \"string\",\r\n      \"description\": \"The person's first name.\"\r\n    },\r\n    \"lastName\": {\r\n      \"type\": \"string\",\r\n      \"description\": \"The person's last name.\"\r\n    },\r\n    \"lastName\": {\r\n      \"type\": \"string\",\r\n      \"description\": \"The person's last name.\"\r\n    },\r\n    \"age\": {\r\n      \"description\": \"Age in years which must be equal to or greater than zero.\",\r\n      \"type\": \"integer\",\r\n      \"minimum\": 0\r\n    }\r\n  }\r\n}\r\n"
}

Using curl:

curl -XPUT -H "Content-type: application/json" -d '{
    "description": "added field for middle name",
    "specification": "{\r\n  \"$id\": \"https://example.com/person.schema.json\",\r\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\r\n  \"title\": \"Person\",\r\n  \"type\": \"object\",\r\n  \"properties\": {\r\n    \"firstName\": {\r\n      \"type\": \"string\",\r\n      \"description\": \"The person's first name.\"\r\n    },\r\n    \"lastName\": {\r\n      \"type\": \"string\",\r\n      \"description\": \"The person's last name.\"\r\n    },\r\n    \"lastName\": {\r\n      \"type\": \"string\",\r\n      \"description\": \"The person's last name.\"\r\n    },\r\n    \"age\": {\r\n      \"description\": \"Age in years which must be equal to or greater than zero.\",\r\n      \"type\": \"integer\",\r\n      \"minimum\": 0\r\n    }\r\n  }\r\n}\r\n"
}' 'http://schema-registry-svc:8080/schemas/<schema-id>'

The response to the schema updating request will be the same as for registering except when the updating is done successfully it will be status 200 OK and a new version will be provided.

{
    "identification": "32",
    "version": "2",
    "message": "schema successfully updated"
}

To get a schema version and its relevant details, a GET request needs to be made and the endpoint needs to be:

http://schema-registry-svc:8080/schemas/<schema-id>/versions/<schema-version>

Using curl:

curl -XGET -H "Content-type: application/json" 'http://schema-registry-svc:8080/schemas/<schema-id>/versions/<schema-version>' 

The response to the schema registration request will be:

• STATUS 200 OK

  {
      "id": "32",
      "version": "1",
      "schema_id": "32",
      "specification": "ew0KICAiJHNjaGVtYSI6ICJodHRwOi8vanNvbi1zY2hlbWEub3JnL2RyYWZ0LTA3L3NjaGVtYSIsDQogICJ0eXBlIjogIm9iamVjdCIsDQogICJ0aXRsZSI6ICJUaGUgUm9vdCBTY2hlbWEiLA0KICAiZGVzY3JpcHRpb24iOiAiVGhlIHJvb3Qgc2NoZW1hIGNvbXByaXNlcyB0aGUgZW50aXJlIEpTT04gZG9jdW1lbnQuIiwNCiAgImRlZmF1bHQiOiB7fSwNCiAgImFkZGl0aW9uYWxQcm9wZXJ0aWVzIjogdHJ1ZSwNCiAgInJlcXVpcmVkIjogWw0KICAgICJwaG9uZSINCiAgXSwNCiAgInByb3BlcnRpZXMiOiB7DQogICAgInBob25lIjogew0KICAgICAgInR5cGUiOiAiaW50ZWdlciIsDQogICAgICAidGl0bGUiOiAiVGhlIFBob25lIFNjaGVtYSIsDQogICAgICAiZGVzY3JpcHRpb24iOiAiQW4gZXhwbGFuYXRpb24gYWJvdXQgdGhlIHB1cnBvc2Ugb2YgdGhpcyBpbnN0YW5jZS4iLA0KICAgICAgImRlZmF1bHQiOiAiIiwNCiAgICAgICJleGFtcGxlcyI6IFsNCiAgICAgICAgMQ0KICAgICAgXQ0KICAgIH0sDQogICAgInJvb20iOiB7DQogICAgICAidHlwZSI6ICJpbnRlZ2VyIiwNCiAgICAgICJ0aXRsZSI6ICJUaGUgUm9vbSBTY2hlbWEiLA0KICAgICAgImRlc2NyaXB0aW9uIjogIkFuIGV4cGxhbmF0aW9uIGFib3V0IHRoZSBwdXJwb3NlIG9mIHRoaXMgaW5zdGFuY2UuIiwNCiAgICAgICJkZWZhdWx0IjogIiIsDQogICAgICAiZXhhbXBsZXMiOiBbDQogICAgICAgIDEyMw0KICAgICAgXQ0KICAgIH0NCiAgfQ0KfQ==",
      "description": "new json schema for testing",
      "schema_hash": "72966008fdcec8627a0e43c5d9a247501fc4ab45687dd2929aebf8ef3eb06ccd",
      "created_at": "2023-05-09T08:38:54.5515Z",
      "autogenerated": false
  }
  

• STATUS 404 Not Found -> indicating that the wrong schema ID or schema version was provided
• STATUS 500 Internal Server Error -> indicating a server error, which means that either the request is not correct ( wrong endpoint) or that the server is down.

Aside from fetching schemas by their ID and version, they can also be fetched using search endpoint. Schemas can be searched on the “/schemas/search?” endpoint, following the search condition. There can be multiple criteria for the search, and they are in the following format: par1=val1&par2=val2&par3=val3. The parameters that schema can be searched upon are as follows:

• id
• version
• type
• name
• attributes

Additionally, they can be ordered by these parameters (except for attributes) in ascending/descending order (the default parameter to order by is ID), as well as limited to a certain number of items. The table below shows a few example of schema search requests (none have body).