Collectors

A collector reads source content into GraphArch's documentation graph. Choose one for the input you have: a Markdown file, an RDF file, a SPARQL endpoint, or another supported source. The table below shows which documentable things each collector can supply.

Documentation generation turns collected content into reference entries, explanations, and diagrams. Renderers present that content as websites or PDFs.

Choose a collector

CollectorInputDocumentable things it supports
RDF File CollectorTurtle, RDF/XML and other supported RDF serializationsOntology resources, families and modules, SHACL shapes, SKOS vocabularies, EKGF use cases, publication hints
RDF URL CollectorAn explicit HTTP(S) RDF document URL and declared media typeOntology resources, SHACL shapes, SKOS vocabularies, EKGF use cases and publication hints
Markdown File CollectorMarkdown with optional YAML frontmatterPages, guides, sections, fenced examples, supported images and Mermaid flowcharts
SPARQL File CollectorAuthored SPARQL textQuery or statement fragments; the query is not executed
SPARQL Endpoint CollectorAn explicit CONSTRUCT or DESCRIBE responseThe same RDF-defined things as an RDF file, with query-result provenance
Published W3C Specification CollectorA saved, published W3C HTML documentSupported specification sections, examples, references, and publication metadata
Legal Preamble CollectorA selected legal disclosure in HTMLLegal preambles explicitly attached to publication targets
Image CollectorSupported PNG, JPEG, or SVG imagesRetained illustrations and product logos
Code Example CollectorAn explicitly selected code fileCode examples published without execution
Text Download CollectorUTF-8 download filesSource-relative website downloads
Repository Publication CollectorGitHub pull requests and Vercel deployment metadataPublication version-selection pages and preserved specification routes
PlantUML DiagramsAn authored PlantUML file and bounded local include closureRetained SVG illustrations with source and renderer provenance
Abbreviation FilesAn authored Markdown abbreviation dictionarySource-owned SKOS meanings and retained dictionary provenance
Publication PeopleORCID iDs in collected sources and GitHub commit authors, through their public APIsEditors and contributors in specification and PDF headers

Repository Scanners discover local files or pinned Git blobs and dispatch the matching file collectors. They provide discovery and source provenance rather than an additional kind of semantic recognition.

See Documentable Things for recognition rules and concrete source examples for each kind of thing. Repository transport does not itself recognise a class, taxonomy, or use case: RDF collectors retain the assertions, and the corresponding documentation generators interpret their explicit types and relationships.

Collection is not always automatic

Directory and repository family builds discover supported RDF files. Website builds discover Markdown pages and selected downloads. The staged CLI exposes individual RDF, Markdown, SPARQL-file, SPARQL-endpoint, and published-W3C collectors. Other collectors are called by specific publishing workflows or the library API; they do not each have a standalone CLI flag. Each page states its entry point.

Independent collectors stream bounded contributions into a shared graph writer. A failure is recorded against its source; configured error policy determines whether independent work continues. A failed contribution cannot silently replace valid source content. See the publication pipeline and quality review.

Add a specialised collector

New source kinds can add small collectors without expanding one catch-all parser. A collector must retain stable identities, source revisions, and provenance, obey resource budgets, and support rendering after the original source has been removed. A new RDF resource kind may instead need a documentation generator over existing RDF collection. See extensibility and the architecture.

Collector additions can be proposed through pull requests following the contribution guide and the extension contract above. Include source and provenance handling, bounded-input regression tests, and a source-free rendering acceptance example.

Collector definitions and configured uses

Collector definitions have canonical RDF identities, such as ga:RdfFileCollector, and are instances of ga:Collector. A source-bound configuration is a separate ga:CollectorUse, linked through ga:collectorType:

@prefix ga: <https://ekgf.org/ontology/grapharch#> .
<urn:my-project> ga:collector <urn:my-source> .
<urn:my-source> a ga:CollectorUse ;
    ga:collectorType ga:RdfFileCollector ;
    ga:source "ontology.ttl" .

Several uses can select the same definition while retaining different sources, configuration, and provenance. The selector must be a supported canonical IRI; string selectors and unknown collector identities fail validation. A configured use selects an existing adapter; declaring a new RDF individual does not install an executable adapter.

Search documentation

Enter words to search this site.