Skip to content

Business Objects Configuration

Business Objects allow administrators to define reusable, structured data views that combine related entity information into a single exportable object. These are particularly useful for external systems that require a simplified or consolidated data format.

Administrators configure how RDF data in Accurids is transformed into Business Objects and, optionally, how these objects are exported to other systems.

Defining a Business Object

Each Business Object is defined using a configuration file (in JSON or YAML). The configuration specifies:

  • The fields to include (strings, numbers, booleans, objects, arrays)
  • How to extract values from the RDF graph (via path mappings)
  • How to structure and nest data (using objects and arrays)
  • Optional features like value templates, filters, visibility, and language preferences

Full Example Configuration (YAML)

Below is an example of a complete Business Object configuration for a disease entity:

type: object
fields:
  uri:
    type: string
  id:
    type: string
    path: <http://www.geneontology.org/formats/oboInOwl#id>
  label:
    type: string
    path: <http://www.w3.org/2000/01/rdf-schema#label>
  synonyms:
    type: array
    path: <http://www.geneontology.org/formats/oboInOwl#hasExactSynonym>
  has_obo_namespace:
    type: string
    path: <http://www.geneontology.org/formats/oboInOwl#hasOBONamespace>
  subclass_of:
    type: array
    path: <http://www.w3.org/2000/01/rdf-schema#subClassOf>
    filter: "label != null"
    elements:
      type: object
      fields:
        uri:
          type: string
        label:
          type: string
          path: <http://www.w3.org/2000/01/rdf-schema#label>
  in_subset:
    type: array
    path: <http://www.geneontology.org/formats/oboInOwl#inSubset>
    elements:
      type: object
      fields:
        uri:
          type: string
        label:
          type: string
          path: <http://www.w3.org/2000/01/rdf-schema#label>

Filtering Which Entities Are Included

The conditions block allows users to filter which entities should be part of the Business Object export.

Each condition includes:

  • A predicate: the property to check
  • A value: the required value for inclusion

Example

"conditions": [
  {
    "predicate": "http://www.w3.org/2000/01/rdf-schema#subClassOf",
    "value": "http://purl.obolibrary.org/obo/DOID_0060038"
  }
]

This ensures only entities that are subclasses of "DOID_0060038" will be included in the export.

Creating a Business Object with Push Configuration

To create or update a Business Object with export functionality enabled (e.g., push to S3), the following API can be used:

PUT /api/v1/business-objects

Example Payload

{
  "id": 1,
  "name": "Human Disease",
  "description": "DOID diseases",
  "enabled": true,
  "config": "type: object\nfields:\n  id:\n    type: string\n    path: <http://www.geneontology.org/formats/oboInOwl#id>\n  label:\n    type: string\n    path: <http://www.w3.org/2000/01/rdf-schema#label>",
  "pushTargets": [
    {
      "bucketName": "doid-diseases-bucket",
      "objectKey": "disease/doid/diseases"
    }
  ],
  "conditions": [
    {
      "predicate": "http://www.w3.org/2000/01/rdf-schema#subClassOf",
      "value": "http://purl.obolibrary.org/obo/DOID_0060038"
    }
  ]
}

Updating Only the Configuration

To update only the Business Object configuration:

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

Triggering Manual Export

Use the following to manually export the latest version of a Business Object:

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

This will regenerate and upload the latest data to the configured destination (e.g., S3).

Automatic Incremental Exports

If a Business Object is configured with push targets and conditions, any updates to relevant entities in Accurids will automatically trigger an incremental export. This ensures that only the changed data is exported, reducing file size and processing overhead.

In the exported file, metadata includes a field such as:

"type": "incremental"

This informs receiving systems that the export only includes modified entities.

When to Use Business Objects?

Use Business Objects when it is needed to:

  • Group multiple entities into a single export unit
  • External systems require simplified, JSON-based data
  • Filter or customize what is included per target system
  • Automate export pipelines and keep external systems up-to-date