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

aria-php / eosc-service-catalogue

Maintainers

Package info

Statistics

Security