README

aria-php/eosc-service-catalogue is a PHP 8.2+ library and CLI that imports a public EOSC service catalogue endpoint and returns a normalized object model.

Core question solved:

Given a URL for an EOSC service catalogue feed, what services does it contain in a normalized object model?

What It Does

• Imports public unauthenticated catalogue URLs over HTTP GET
• Detects feed format by content
• Supports native EEN JSON and DCAT-compatible JSON-LD
• Follows explicitly advertised pagination
• Normalizes records to stable ServiceCatalogue and Service objects
• Preserves warnings, provenance, and raw source documents for debugging
• Exposes serializers (array, JSON, DCAT JSON-LD)
• Ships with CLI inspection command

What It Does Not Do

• Node discovery or endpoint crawling
• Authentication to private catalogues
• Full RDF engine or SHACL runtime validation
• Persistent storage
• Harvest scheduling
• Cross-catalogue deduplication

Installation

composer require aria-php/eosc-service-catalogue

Library Usage

<?php

declare(strict_types=1);

use EOSC\ServiceCatalogue\ImportMode;
use EOSC\ServiceCatalogue\ServiceCatalogueImporter;

$importer = ServiceCatalogueImporter::createDefault();

$catalogue = $importer->import(
    'https://node.example.org/catalogue/services',
    mode: ImportMode::TOLERANT,
);

foreach ($catalogue->getServices() as $service) {
    echo $service->getId() . ' ' . ($service->getName() ?? '(unnamed)') . PHP_EOL;
}

Import Modes

• strict: fail on malformed payloads, unsupported format, rejected required fields, and unknown required controlled values
• tolerant: preserve unknown values with warnings where possible and skip only unsafe records
• best_effort: mint local non-official concepts for unknown controlled values and preserve as much as possible

Pagination Support

Pagination is followed only when clearly advertised by:

• HTTP Link header (rel="next")
• Body-level next, nextPage, or links.next

Guardrails:

• max pages
• max records
• repeated URL detection
• loop detection errors
• optional disable (followPagination=false)

CLI Usage

Binary:

vendor/bin/eosc-catalogue-import

Examples:

vendor/bin/eosc-catalogue-import inspect https://node.example.org/catalogue/services
vendor/bin/eosc-catalogue-import inspect https://node.example.org/catalogue/services --mode=strict
vendor/bin/eosc-catalogue-import inspect https://node.example.org/catalogue/services --no-pagination
vendor/bin/eosc-catalogue-import inspect https://node.example.org/catalogue/services --show-warnings
vendor/bin/eosc-catalogue-import inspect https://node.example.org/catalogue/services --format=json
vendor/bin/eosc-catalogue-import inspect https://node.example.org/catalogue/services --format=json --pretty
vendor/bin/eosc-catalogue-import inspect https://node.example.org/catalogue/services --format=dcat-jsonld
vendor/bin/eosc-catalogue-import inspect https://node.example.org/catalogue/services --summary

Warning and Exception Behavior

Warnings are attached to catalogue and/or service records and include severity, code, and source context.

Strict failures throw StrictImportException with context payloads including input URL, page URL where relevant, parser and warning trail.

Node Discovery Integration

The package is discovery-agnostic. For integration with a separate node discovery library, use:

• EOSC\ServiceCatalogue\Bridge\NodeDiscoveryAdapter

It accepts a discovered capability payload (endpoint/url, optional format) and delegates to the importer.

Development

Run tests:

composer test

Run static analysis:

composer stan

Run full checks:

composer check

Supported Input Formats

• Native EEN JSON
• DCAT JSON-LD (structural parsing, no full RDF expansion in v1)

License

LGPL-3.0-or-later