Business Objects Configuration

Business Objects allow administrators to define structured, reusable data views that support both importing and exporting data through the Accurids platform.

They are designed for controlled, automated data exchange — ensuring that:

external systems receive validated, business-ready JSON, and
structured JSON can be imported into Accurids without interacting with RDF directly.

Administrators configure:

How RDF data is transformed into or from structured JSON
Which objects are included or created based on conditions
Where data is delivered or received (e.g., S3, API)
When exchanges are triggered (manual or automatic)

Accessing the API

To access and explore the Accurids Public API, navigate to https://your-accurids-domain/api.

The API provides endpoints for defining, updating, importing, and exporting Business Objects.

1. Defining a Business Object

A Business Object is defined via a configuration file (in YAML or JSON) that maps RDF data in Accurids to a structured JSON format. Each configuration specifies:

Fields to include (e.g., strings, numbers, booleans, objects, arrays)
Paths for data extraction (RDF predicates or linked objects)
Nested structures for related objects
Optional filters, conditions, or templates for customization
Push targets for defining where exports are delivered (e.g., S3, API)

Example YAML 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>

Example with Array Fields

Arrays can be defined to handle properties with multiple values, such as emails, phone numbers, or identifiers. They are declared using type: array with an elements block describing the contained 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

Arrays can also contain nested objects for more complex relationships.

2. Ingestion Prerequisites

Before ingesting JSON data into Accurids:

The PID Generator module must be active for URI minting.
All referenced namespaces must exist and match the configuration.
The Business Object must be enabled.
Input JSON must strictly follow the configured field structure.

Ingestion Modes

When importing data into a Business Object, Accurids supports two ingestion modes that define how existing data is handled and updated.

Mode	Description	Typical Use Case
ADD	Adds new objects and merges new data into existing ones. Existing information is preserved — Accurids appends any additional fields or values from the incoming payload.	Incremental enrichment or non-destructive updates where existing data should remain intact.
REPLACE	Replaces all existing data for matching objects (based on URI). The previous statements for these objects are deleted and fully replaced with the new payload content.	Controlled synchronization or complete data refresh scenarios.

Example Behavior

Existing object:

{
  "uri": "https://id.accurids.com/person/1",
  "name": "Alice"
}

Incoming payload:

{
  "uri": "https://id.accurids.com/person/1",
  "name": "Bob"
}

With mode=ADD: → result = name: ["Alice", "Bob"]
With mode=REPLACE: → result = name: "Bob"

Example Endpoints

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

or

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

If no mode is specified, ADD is used by default.

3. Change Owners

Business Objects can optionally define change owners. Change owners are users and/or groups that should also be able to access the pending changes created by Business Object ingestions, even if they did not execute the ingestion API call themselves.

This is useful when Business Objects are executed by service accounts, but review and stewardship should be handled by specific people or teams.

Configuration

Add entityChangeOwners to the Business Object definition:

{
  "entityChangeOwners": {
    "groups": [
      "Group Name"
    ],
    "users": [
      "reviewer1@accurids.com",
      "reviewer2@accurids.com"
    ]
  }
}

Effect

When accurids.pending-changes.skip=false (pending review enabled):

the API user that triggered ingestion can access the created pending changes, and
the configured change owners can also access the same pending changes (additional visibility).

Because change owners gain access to the pending changes, they can also perform the same workflow actions that their role permits — for example moving changes forward (approval) or moving changes backward (rejection / send back to a previous stage).
See Pending Changes for details on lifecycle stages and forward/backward transitions.

If no owners are configured, access is limited to the ingestion user.

4. Filtering Included Objects

The conditions block defines which objects are processed during import and export.

"conditions": [
  {
    "predicate": "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
    "value": "https://schema.org/Person"
  }
]

Only objects matching the condition will be included.

5. Creating or Updating a 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"
    }
  ]
}

6. Updating Configuration Only

PUT /api/v1/business-objects/{id}/config

Replaces the configuration while keeping existing metadata.

7. Automation and Scheduling

Business Objects can be processed automatically:

On schedule — via a cronExpression
On data changes — incremental updates
After ingestion — trigger exports automatically

Example schedule:

"cronExpression": "0 0 * * *"

Runs daily at midnight (UTC). Accurids uses standard cron syntax.

8. Metadata and Integrity

Every Business Object export includes metadata for verification and traceability.

Field	Description
`object_type`	Business Object name
`export_date`	Timestamp (UTC)
`object_count`	Number of exported objects
`data_checksum`	SHA-256 checksum for file integrity
`checksum_algorithm`	Hashing algorithm used

Accurids uses a FIFO queue to ensure stable, ordered exports — even in case of retries or temporary interruptions.

9. Troubleshooting

Problem	Cause	Solution
Ingestion failed: null	Invalid YAML or namespace mismatch	Verify YAML structure and dataset tags
No objects exported	Condition mismatch	Ensure predicate and value match dataset
Export missing	Push configuration issue	Check bucket name and permissions
Nested data missing	Incorrect paths or namespace	Ensure nested fields are valid and linked correctly

When to Use Business Objects

Use Business Objects to:

Automate data imports and exports
Standardize external data interfaces
Keep business logic consistent across systems
Maintain full traceability of changes and identifiers