Skip to content

DFC LinkML SDK

TypeScript, Ruby, and PHP connectors for the Data Food Consortium (DFC) standard, generated from the DFC LinkML schema and pinned to DFC v2.0.0.

All three connectors are generated from one schema, so they agree on data plane, predicates, and round-trip behaviour. Where they differ it is naming, and the differences are documented rather than smoothed over.

Install

npx jsr add @siol-data/linkml-connector

Published to jsr.io. That writes an @jsr:registry line to your .npmrc and adds the dependency, so plain npm install works afterwards.

gem install dfc-linkml-connector

composer require siol-data/dfc-connector

packagist.org reads composer.json from the repository root of DFC-LinkML, so this installs from that repo directly.

Hello, DFC

import { Connector } from "@siol-data/linkml-connector";

const c = new Connector();

const org = c.createOrganization("https://example.com/org/1", {
  name: "Acme Farms",
});

console.log(await c.export(org));

connector = DfcLinkmlConnector::Core::Connector.new
org = DfcLinkmlConnector::Models::Organization.new(
  "https://example.com/org/1", name: "Acme Farms"
)
puts connector.export(org)

$connector = new \DataFoodConsortium\Connector\Connector();
$org = $connector->createOrganization("https://example.com/org/1", [
    'name' => 'Acme Farms',
]);
echo $connector->export($org);

{
  "@context": "https://w3id.org/dfc/ontology/v2.0.0/context/context_2.0.0.json",
  "@id": "https://example.com/org/1",
  "@type": "dfc-b:Organization",
  "dfc-b:name": "Acme Farms"
}

TypeScript and Ruby emit @context first and PHP emits it last. The content is identical; only the key order differs, and JSON key order carries no meaning. Do not compare exported documents byte-for-byte — the round-trip tutorial explains why.

Where to go next

Start with the getting started overview, then hello-dfc and the JSON-LD round trip. Together they are about five minutes and cover construct, export, and import.

Read the migration guide first — it maps the original API to this one property by property. The API gap tables and Ruby gaps are generated and exact; the guide is the narrative around them.

Task-oriented recipes in the guides: build a catalog, read and validate JSON-LD, handle identifiers, and work offline.

The model reference is generated from the schema: 89 classes, 255 properties, and the five controlled vocabularies with every concept. The API reference is parsed from the three connector sources, so it cannot describe a method that does not exist. The conformance report is the scoreboard: every fixture document against every connector, regenerated on each release so it cannot go stale.

The concepts section explains identifiers, relationships, context and versioning, vocabularies, and validation — including which of those the toolchain actually implements.

Architecture for how generation fits together, generation for the pipeline and how to run it, SDK contract for the cross-language surface the three connectors are held to, and licensing for why there are two licences.

The mental model in four lines

  • Objects are yours. You choose the @id; the connectors never generate or validate one.
  • Relationships are links, not copies. A reference serialises as an @id, and a single-valued one is a scalar even if you set a one-element array.
  • The context is a URL and it is bundled. v2.0.0 works entirely offline.
  • Nothing validates your data. The connectors preserve and normalise; they do not reject. A round trip keeps only what the schema says the class can hold, so your own predicates do not survive it. See property retention.

Licence

The generated connectors are MIT licensed. The LinkML codebase that generates them is AGPLv3 — see the licence notes.