Skip to content

Business Objects

Business Objects are reusable, structured data views that enable controlled data exchange between Accurids and external systems.

They can be used for both importing and exporting data in clean, business-ready JSON — without exposing the underlying RDF complexity.

Business Objects make it easy to exchange data with other applications, integrate pipelines, or automate synchronization workflows — all while preserving Accurids’ semantic structure and data quality.

What Are Business Objects?

A Business Object defines a consistent structure for exchanging data between Accurids and external systems. It specifies:

  • What information to include — such as names, codes, or linked objects
  • How to organize the data — using flat or nested JSON structures
  • Which objects to include — using filters or conditions
  • Where data flows — via import endpoints or automated exports

Business Objects act as reusable data interfaces — simplifying data ingestion, transformation, and delivery.

Why Use Business Objects?

Business Objects allow you to:

  • Import structured data into Accurids using JSON
  • Export validated and curated data to external systems
  • Automate both directions via schedules or event triggers
  • Ensure traceability with persistent identifiers (PIDs)
  • Keep integrations reliable with a consistent, versioned schema

By defining a Business Object once, data exchange becomes reliable, transparent, and bi-directional.

Creating a Business Object

Creating a Business Object involves defining what data it includes, how it is structured, and how it is exchanged.

1. Define Namespaces

Each Business Object operates within a namespace, which defines how persistent URIs are generated.

Example:

Name: Person
URI base: https://id.accurids.com/person

See Namespace Management for more details.

2. Define the Structure (Configuration)

A Business Object configuration is written in YAML. It maps Accurids properties to fields in the exchanged JSON structure.

Example Configuration

type: object
path: Person:.
fields:
  uri:
    type: id
  type:
    type: resource
    path: <http://www.w3.org/1999/02/22-rdf-syntax-ns#type>
  first_name:
    type: string
    path: <https://schema.org/givenName>
  last_name:
    type: string
    path: <https://schema.org/familyName>
  email:
    type: string
    path: <https://schema.org/email>
  address:
    type: object
    path: <https://schema.org/address>/Address:.
    fields:
      uri:
        type: id
      street:
        type: string
        path: <https://schema.org/streetAddress>
      city:
        type: string
        path: <https://schema.org/addressLocality>

This defines a Person object with an embedded Address.

Example with Array Fields

Arrays can be used to represent multi-valued properties such as emails, phone numbers, or aliases. Define them using type: array and an elements block describing the data type.

type: object
path: Person:.
fields:
  uri:
    type: id
  first_name:
    type: string
    path: <https://schema.org/givenName>
  last_name:
    type: string
    path: <https://schema.org/familyName>
  emails:
    type: array
    path: <https://schema.org/email>
    elements:
      type: string
  phone_numbers:
    type: array
    path: <https://schema.org/telephone>
    elements:
      type: string

This example defines a Person object with multiple emails and phone_numbers.
Arrays can contain simple strings or nested objects depending on your configuration needs.

3. Create the Business Object

Endpoint:

PUT /api/v1/business-objects

Example request:

{
  "name": "Person",
  "description": "Business Object for Person data with nested Address",
  "enabled": true,
  "config": "type: object\npath: Person:.\nfields:\n  uri:\n    type: id\n  first_name:\n    type: string\n    path: <https://schema.org/givenName>\n  last_name:\n    type: string\n    path: <https://schema.org/familyName>\n  email:\n    type: string\n    path: <https://schema.org/email>",
  "conditions": [
    {
      "predicate": "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
      "value": "https://schema.org/Person"
    }
  ],
  "pushTargets": [
    {
      "bucketName": "company-businessobject"
    }
  ]
}

Ingesting Data

Once a Business Object is configured, data can be uploaded in JSON format.
If URIs are not provided, Accurids automatically generates Persistent Identifiers (PIDs).

Endpoint:

POST /api/v1/business-objects/{id}?mode=ADD

Example Payload

{
  "data": [
    {
      "first_name": "Andrea",
      "last_name": "Zenoni",
      "email": "azenoni@example.com",
      "address": {
        "street": "Central Street 12",
        "city": "Basel"
      }
    }
  ]
}

If uri is omitted, Accurids automatically creates one (e.g., https://id.accurids.com/person/1).

Example with Array Data

{
  "data": [
    {
      "first_name": "Andrea",
      "last_name": "Zenoni",
      "emails": [
        "azenoni@example.com",
        "a.zenoni@accurids.com"
      ],
      "phone_numbers": [
        "+41 61 123 45 67",
        "+41 79 999 88 77"
      ],
      "address": {
        "street": "Central Street 12",
        "city": "Basel"
      }
    }
  ]
}

When ingested, all array elements are stored and linked to the same Person object.

Nested Business Objects

Business Objects can include nested structures to represent linked data. Each nested object is stored in its own namespace and connected to its parent automatically.

Example:

{
  "studyCode": "ST-001",
  "studyName": "Toxicology Evaluation",
  "groups": [
    {
      "groupCode": "GR-01",
      "groupName": "High Dose Group",
      "animals": [
        {
          "animalId": "A-001",
          "species": "Rat",
          "samples": [
            {
              "sampleId": "S-001",
              "sampleType": "Blood",
              "collectionDate": "2025-03-15"
            }
          ]
        }
      ]
    }
  ]
}

When ingested, Accurids automatically creates identifiers and preserves all hierarchical relationships.

Exporting Business Objects

Business Objects can be exported manually or automatically.

Manual Export

GET /api/v1/business-objects/{id}/push

Automatic Export

Exports can be triggered automatically:

  • On schedule (via cron expression)
  • On data changes (incremental push)

Example exported file:

{
  "metadata": {
    "export_date": "20251027T100542Z",
    "object_type": "Person",
    "object_count": 1,
    "data_checksum": "34c99c7568cb511836aa4b561727371e3c85f64f4c0bf134974fb1aabbed46dd",
    "checksum_algorithm": "SHA-256"
  },
  "data": [
    {
      "uri": "https://id.accurids.com/person/1",
      "first_name": "Andrea",
      "last_name": "Zenoni",
      "email": "azenoni@example.com"
    }
  ]
}

Accurids uses a FIFO (First In, First Out) mechanism for stable, ordered exports even when delayed or interrupted.

Monitoring and Validation

  • Each ingestion and export is logged in the system.
  • Exports to S3 or other targets appear automatically after processing completes.
  • Large or nested datasets may take longer to process.

Troubleshooting

Problem Possible Cause Solution
Ingestion failed: null Invalid YAML or namespace mismatch Ensure all namespaces match the configuration paths
No objects exported Condition not met Verify that the predicate and value match the data type
Export incomplete Interrupted push or S3 issue Check logs for retries or verify bucket permissions

Learn More

Note: In some setups, Business Object ingestions can assign change owners so that specific users or groups can also access the pending changes created by an ingestion, even if they did not run the API call themselves.

See Business Objects Configuration for technical configuration details and advanced mapping options.