GET [TypeIndexService]

Returns a paginated TypeIndex as application/lws+json, following the standard LWS pagination model defined by [[!LWS-PROTOCOL]]: page URIs are conveyed in Link headers—not in the response body—and are opaque to the client. The body lists the unique types of resources that currently exist within the storage and that the authenticated user is authorized to see. This endpoint accepts no query parameters.

HTTP/1.1 200 OK
Content-Type: application/lws+json
Link: <https://example.org/types/index?page=1>; rel="first"
Link: <https://example.org/types/index?page=2>; rel="next"
Link: <https://example.org/types/index?page=4>; rel="last"

{
  "@context": "https://www.w3.org/ns/lws/v1",
  "type": "TypeIndex",
  "totalItems": 142,
  "items": [
    { "id": "https://schema.org/Person" },
    { "id": "https://schema.org/Event" },
    { "id": "https://schema.org/Message" }
  ]
}
        

GET [TypeSearchService]

The type query parameter is OPTIONAL and selects resources by their rdf:type (as declared via rel="type" Link headers, server-intrinsic classes, or content; see ).

A single type parameter MAY carry a comma-separated list of URIs, combined with logical OR — a resource matches the group if it declares any of the listed types. Repeating the type parameter combines the groups with logical AND. The filter is therefore a conjunction of disjunctions: ?type=A,B&type=C selects resources matching (A OR B) AND C. A request with no type parameter matches all resources visible to the client.

This conjunctive-normal-form filter is the complete query expressiveness of the service. Servers MAY support nesting, negation, comparison, ordering, or text matching. A type URI that matches no resource yields no results and MUST NOT be treated as an error; empty or duplicate groups MUST be ignored.

The type parameter is the mandatory baseline and MUST be supported by every server that implements the TypeSearchService. A server MAY additionally index other descriptive link relations. Such a relation is filtered by using the relation itself as the query-parameter name — a registered relation name per [[!RFC8288]] or, for an extension relation, its URI — with exactly the same conjunctive-normal-form semantics as type (comma = OR group, repeated parameter = AND group, target values matched against the link targets the resource declares for that relation). Groups belonging to different relations are combined with logical AND. Relation targets are derived by the server in the same way as types (HTTP Link headers, server-intrinsic state, or parsed content) and all sources MUST be treated identically.

The set of additional indexed relations is deliberately NOT enumerated by the server — not in the storage description nor elsewhere — so that it cannot serve as a discovery oracle. A relation the server does not index, like a target value that matches nothing, simply yields no results for that constraint; it MUST NOT be treated as an error, and the two cases MUST be indistinguishable to the client (consistent with the type-matching rule above). Servers MUST NOT index structural or protocol relations, only descriptive relations are eligible.

Clients MUST URL-encode query parameter keys and values.

Returns application/lws+json: A paginated ContainerPage whose items describe the matching LWS resources. Aside from type and any additional relation parameters described above, no other parameters are defined.

A ContainerPage returned by the TypeSearchService is a synthetic result set, not a representation of a container resource. The ContainerPage media type and pagination model are reused only for client convenience; the response does not identify a container, has no containment relationship to its members, is not retrievable or mutable as a resource, and its membership reflects the query rather than any stored hierarchy. Each item is a resource description carrying at least id and type, mirroring a container member; a server MAY include additional descriptive metadata (such as mediaType, size, or modified) but is not required to. The same applies to the POST form.

A single-type query (one URI, no comma) matches a resource that declares that type, even if the resource also declares other types.

A type filter always denotes the type the matched resource itself bears; it never denotes the types of a container's members. The native LWS classes https://www.w3.org/ns/lws#DataResource and https://www.w3.org/ns/lws#Container are ordinary type values: filtering on them selects resources that are themselves data resources or containers, respectively (for example ?type=https://www.w3.org/ns/lws%23Container matches container resources, and ?type=https://schema.org/Person&type=https://www.w3.org/ns/lws%23DataResource matches data resources that are also schema:Person).

POST [TypeSearchService]

MUST support application/lws+json body:

{
  "@context": "https://www.w3.org/ns/lws/v1",
  "type": [
    ["https://schema.org/Person", "http://xmlns.com/foaf/0.1/Person"],
    "https://www.w3.org/ns/lws#DataResource"
  ]
}
        

type: an array whose elements are combined with AND. Each element is either a single type URI or an array of type URIs combined with OR. The example above selects resources matching (schema:Person OR foaf:Person) AND lws:DataResource. This is the same conjunctive-normal-form filter as the GET form, with the same expressiveness ceiling: servers MUST NOT be required to support nesting, negation, comparison, ordering, or text matching.

The body MAY also include, alongside type, a key for any other descriptive relation (a registered relation name per [[!RFC8288]] or an extension relation URI). Each such key takes the same value form as type and the keys are combined with logical AND, exactly as in the GET form. A relation the server does not index yields no results for that constraint and is indistinguishable from a target value that matches nothing; it MUST NOT be treated as an error.

Returns a paginated ContainerPage whose items describe the matching LWS resources. Aside from type and additional relation keys, no other parameters are defined.

Request Equivalence and Errors

A server implementing the TypeSearchService MUST support both the GET and POST forms. The two forms are equivalent: any filter expressible in one MUST be expressible in the other, and equivalent GET and POST requests MUST return the same result set. A server MUST NOT impose different expressiveness limits on the two forms, except that GET requests are additionally bounded by practical request-URI length limits.

Servers indicate request outcomes using standard HTTP status codes. In particular:

• A POST body that is not well-formed application/lws+json, or whose type is not an array, or any of whose elements is neither a string nor an array of strings, MUST be rejected with 400 (Bad Request).
• A POST request whose entity uses a media type other than application/lws+json MUST be rejected with 415 (Unsupported Media Type).
• A type value, or any relation target value, that is not a syntactically valid absolute URI MUST be rejected with 400 (Bad Request). This is distinct from a well-formed URI that matches no resource, and from a relation the server does not index, both of which yield no results and are not errors (see above).
• A pagination reference (a previously issued next link) that the server no longer recognizes or that has expired MUST result in 404 (Not Found) or 410 (Gone); clients SHOULD restart the query from the first page.
• A filter that exceeds the complexity a server chooses to support (consistent with the expressiveness ceiling above) MUST be rejected with 400 (Bad Request). A server MUST NOT silently truncate or otherwise narrow such a filter, as doing so could return a superset of the intended results.

Error responses MAY include a representation describing the problem; this specification does not define its format.