Common entity schema
http://developers.ros.gov.uk/schema/common/schema.json

Overview

• Primitives
• Formats
• Patterns

The following is a collection of entities and formats which are inspired, but not necessarily directly lifted from our existing applications.

It's recommended to use them in the following ways:

• When representing the same kind of data, we should where possible use the same structure
• The following should be taken as 'super' cases of the items we need. Not every field will be required in every setting. We should however attempt to use degenerate versions of the existing structures.
• If a structure is related, but doesn't seem to quite fit a new use case, it's a good time to bring it up for discussion.

Primitives

The schema provides a number of non domain specific entities for use in other schema.

General

• Coded value - items in controlled lists of values
• Contact details - for email addresses, phone numbers etc.
• Structured address - an address with items like street rather than line1, line2

People and Companies

We provide the following elements for representing people and companies:

• Person - a person with a person name
• Company - a company with a company name
• Party - either a person or company distinguished by type
• Agent - a person with a company

Formats

This schema provides a number of distinct formats which you can reference to prevent you from having to repeat yourself in your schema.

You can include these by using a JSON schema reference:

{
    "type": "object",
    "properties": {
        "myFasNumber": {
            "$ref": "http://developers.ros.gov.uk/schema/common/schema.json#/fasNumber"
        }
    }
}

Other formats are available in domain specific schema.

Patterns

The schema provides a few examples of common patterns used in RoS schema.

These are not intended to be directly referenced, but to provide examples and some explanation of some patterns you may encounter.

The root element here is nonsense. You wouldn't want to validate a data structure against the root schema; this schema is only intended to be used to reference the individual entities described in it.

An agent is a person who works for a company. Although both the agent and their company are full person and company entities, in most use cases, only a small number of the possible fields are actually expected or used by the application.

Typically this will be a solicitor in a Land Registry context. Many different solicitors may work for the same company and therefore may share the same company details.

Field notes

• Even though we know the agent is a person the type field is still present for compatibility with party entities.
• In the case of agents, the type of the company (non_natural or non_natural_uk) is irrelevant, and it is perfectly acceptable to use non_natural for all cases.

The common format used to represent all coded lists of values.

Discovering the right values

Whenever you see this entity, you should always see it accompanied by a format telling you what values are expected.

In the following example we can see a well formed reference to a coded value:

{
    "allOf": [
        {"$ref": "http://developers.ros.gov.uk/schema/common/schema.json#/codedValue"},
        {"property": {
            "code": {"format": "ref:lr/application/type"}
        }}
    ]
}

It has:

• An allOf which states that this is a codedValue
• An additional schema which sets the reference format
• The format specified begins with ref: telling you this is a value from the Reference API
• The format after the colon tells you the path to retrieve the coded list in the Reference API
• It could have also included an enum if the list is small and static

Using this entity without a reference format is considered an error.

The common format used to represent coded lists of values where custom values are allowed.

This entity extends coded value with the option of specifying the other code, in which case the prettyPrint value must be sent and will be read by the server side.

Using this entity without a reference format is considered an error.

Represents a non-natural person (a company or organisation).

In general non_natural_uk companies are a subset of non_natural companies. Therefore for applications where the distinction is irrelevant (such as in the agent) it is perfectly acceptable to set the type to non_natural.

Field notes

For Non-UK companies:

• The allocatedNumber is optional

For UK companies:

• The ukCompanyNumber is mandatory
• As the ukCompanyNumber is a more specific case of an allocatedNumber, UK companies should set both (the same)

A company name.

Note that the company prefix unusually references two reference lists:

• If the type of the containing company is non_natural the format must be ref:core/company/name/prefix
• If the type of the containing company is non_natural_uk the format must be ref:core/company/name/prefix/uk

You do not need to provide the prettyPrint fields as these will be automatically created.

An entity for containing contact details.

Patterns are not referenced in external schema, but represent common patterns and the thinking behind them.

If you are representing boolean values, the name should always begin with is, even if this is slightly grammatically awkward.

For example:

• isNotAvailable - If a negation is required
• isWithAttachments - Where perhaps hasAttachments might be more natural

Dates should be nested into an object which only contains flat key value pairs, where all values are dates in RFC3339 format.

Any time the single key date is used in any schema, it should refer to a flat object with dates inside.

A schema using the date field in another way would be considered an error

This is more of a practice than a particular schema. The pretty print field is intended to provide a human readable summary of the object at it's level in the hierarchy for just about any object it might be useful for.

As the submitter of data you almost never need to send prettyPrint. The only counter example is in coded values or other when submitting other.

• The value is for human benefit, not for automated usage
• The value should be automatically generated from the other fields in the object
• As a result, the value is usually ignored by the back end (and regenerated)
• This relieves people submitting data to the service from having to understand the logic of creating the field
• The result represents the object at the level it is and below (not above, closer to the root)
• There is no generic solution for creating prettyPrint strings. They tend to be domain specific (even for the same object type)
• It's useful for:
  • Making user interfaces
  • Debugging
  • Inserting merged data into old systems that don't separate different parts of the data

This is a block intended to store references to this block in other systems, but is not intended for the primary entity id.

There's not much to see, basically it's a flat object where the values are interpreted as external references.

A number used to identify the account to charge for various transactions.

Although the schema states that the format is just four digits, in truth only certain FAS numbers are valid, and each is associated with a particular user.

In addition, certain FAS numbers are associated with certain payment methods (cheque/direct debit), and therefore may be invalid if provided in the wrong context.

Represents a person or company when you don't know which you are going to get.

Parties are either natural or non-natural.

• "Natural people" - are actual individual humans
• "Non-natural people" - are companies and organisations
• UK companies are specifically coded separately from international companies (see company)

The person or company entities are designed to share many fields, so that in many cases they can be treated identically.

Specifically, all parties have:

• A type field, which must match the entity type.
• name.prettyPrint
• address
• contact - Contact details

Represents a natural person (a human).

Although there is only one possible value for type, you still need to supply it to distinguish between a person and a company when used as part of a party). See party for more details of natural and non-natural people.

A person's name.

Field notes

• The prefix includes only formal titles rather than a common titles
• The prefix therefore does not include values like 'Mr'
• There is currently no way of submitting common titles
• Common titles are not used by Registers of Scotland

This is to store structured addresses where we know which item is which, as opposed to addresses expressed as an array of "lines".

The main address structure is a great deal more fully featured than most applications can accept. It will therefore be up to applications to specify what fields are required or accepted in their specific cases.

Field notes

• As always, no effort should be spent constructing the prettyPrint fields, as they are ignored and recalculated by the receiving application.
• The country codes are the ISO 3166-1 alpha-2 codes. In the event that you need to supply an uncoded country, you can use the 'ZZ' code (as the code is mandatory), but be aware that many consumers will discard the value in this case.

Represents a user interacting with one of our systems.

Although the username is simply stated to be a string, only valid usernames will work. The valid usernames will differ from system to system.