Pod Shared

| solid-pod links <url> | Outgoing references from .meta | | solid-pod types <url> | Browse rdf:type values with counts | | solid-pod backlinks <url> | Find resources linking to this URL | | solid-pod create <container-url> | Create resource (PUT + PATCH .meta) | | solid-pod patch <url> | N3 Patch to .meta sidecar | | solid-pod search <url> <terms> | Text search across .meta files (OSLC-ready, SPARQL fallback) | | solid-pod properties <url> | Predicate usage statistics from .meta files |

Output Format

Every response is JSON-LD compact form with standard prefixes:

{
  "@context": {
    "ldp": "http://www.w3.org/ns/ldp#",
    "dct": "http://purl.org/dc/terms/",
    "skos": "http://www.w3.org/2004/02/skos/core#",
    "sh": "http://www.w3.org/ns/shacl#",
    "void": "http://rdfs.org/ns/void#",
    "solid": "http://www.w3.org/ns/solid/terms#",
    "prof": "http://www.w3.org/ns/dx/prof/",
    "prov": "http://www.w3.org/ns/prov#"
  },
  "@id": "http://pod.vardeman.me:3000/vault/resources/concepts/",
  "@type": "ldp:Container",
  "affordances": { ... }
}

The affordances field surfaces HTTP Link headers as structured data:

These tell you what you can do next. Follow them.

Four-Layer Self-Description

A Solid Pod describes itself through four layers. Each layer adds richer context:

L1: .well-known/solid         VoID + DCAT       What's in this pod?
L2: SolidPodProfile           PROF descriptors   Where are schemas, shapes, guidance?
L3: /procedures/shapes/*.ttl  SHACL shapes       How should I query/validate?
L4: /procedures/queries/      SPARQL examples    Show me working queries.

L1 (Discovery): GET /.well-known/solid returns VoID dataset descriptions (classes, vocabularies, entity counts) and DCAT catalog metadata. This is the entry point. The solid-pod info command reads this layer.

L2 (Structure): The SolidPodProfile (a PROF Profile) links to schemas (role:schema), constraints (role:constraints), and guidance (role:guidance) via PROF ResourceDescriptors. These are the connective tissue between layers.

L3 (Validation + Guidance): SHACL shapes define expected properties per resource type. Crucially, sh:agentInstruction (SHACL 1.2 S8.3) tells agents which SPARQL patterns to use, which predicates matter, and how to interpret results. This is the key piece for agent reasoning.

L4 (Examples): Pre-built SPARQL queries generated from shapes. Agents can use these directly or adapt them.

Key Principle

The pod describes itself. Read the affordances. Follow the links. The structure IS the documentation. An agent needs no external configuration to navigate a well-described pod.

Discovery Workflow

1. solid-pod info <url>            Read .well-known/solid (L1)
2. Follow SolidPodProfile          Find shapes, schemas (L2)
3. solid-pod shapes <url>          Read sh:agentInstruction (L3)
4. solid-pod properties <url>      Learn actual predicates in a container
5. solid-pod sparql <url> ...      Use discovered patterns (L3-L4)
   solid-pod search <url> <terms>  Or text search for quick discovery
6. solid-pod read <url>/path       Browse resources with affordances

Reference

For Solid protocol details (LDP operations, N3 Patch format, .meta sidecar pattern, SHACL agent guidance, Comunica gap), see references/solid-patterns.md.