A shared definition of the things a business runs on.

Every system has its own idea of a customer. Business Schema defines it once, in the open: the properties it has, which of them are personal data, and how to tell that two systems are describing the same one.

Types

Type	Kind	Describes	Properties
Entity	Base entity	Identity shared by every business entity.	2
Customer	Entity	A person or organization with a potential, current or former customer relationship with the business.	21
Address	Value type	A postal address, with who it is addressed to.	9
External reference	Value type	An opaque ID in another system, optionally scoped to an account or brand.	2
Organization	Value type	A company or other legal body, and how it is registered.	5
Person	Value type	An individual: how they are named and when they were born.	7

An entity has its own identity and life. A value type is a reusable shape held inside an entity, such as an address on a customer.

Using the schema

Read a definition

Each type is published as a page for people and a JSON document for software. The whole release is one catalogue.

curl https://business-schema.org/customer.json
curl https://business-schema.org/catalogue.json

Shape your records to match

A record is a JSON object keyed by the type's property keys. Every entity has an id and can link to IDs in other systems through external_references. Value types nest; collections can be keyed by labels, lists, or lists under each label.

{
  "id": "customer_123",
  "external_references": {
    "stripe/customer": [
      {
        "routing_key": "brand_1",
        "id": "cust_32HDDsd"
      },
      {
        "routing_key": "brand_2",
        "id": "cust_87ABCxy"
      }
    ],
    "fortifi/customer": [
      {
        "id": "CST_456"
      }
    ]
  },
  "party_type": "individual",
  "display_name": "Alex Morgan",
  "primary_contact": {
    "given_name": "Alex",
    "family_name": "Morgan"
  },
  "email": "alex.morgan@example.com",
  "phone": "+447700900123",
  "addresses": {
    "billing": {
      "line1": "1 High Street",
      "city": "London",
      "postal_code": "SW1A 1AA",
      "country": "GB"
    }
  },
  "country": "GB",
  "language": "en-GB",
  "currency": "GBP",
  "lifecycle_stage": "customer",
  "status": "active",
  "timezone": "Europe/London",
  "is_test_account": false,
  "commercial_model": "paid",
  "billing_stage": "trial",
  "payment_status": "none"
}

Load it from Go

The Go module carries the definitions it was released with, so upgrading is a deliberate change to your dependencies.

go get github.com/business-schema/schema

catalogue, err := schema.Load()
customer, _ := catalogue.Entity("customer")

What a definition tells you

Shape: Each property's type and format, such as a date, a country code or a nested value type.
Personal data: Which properties identify a person, and which should stay masked until someone asks to see them.
Matching: Which property identifies the same record in another system, and when two values count as equal.
Life: For entities: the statuses a record moves through, the actions that change it and the events those raise.
Equivalents: Where a term matches one in schema.org, the definition links to it.

Status

This is a draft. Definitions may change incompatibly until version 1.0. From 1.0, a change within a major version only adds.