Document discovery of a ServiceInfo document. Adopt the JSON-LD.

Discovery happens via host-meta lookups or referencing a ServiceInfo
context provided serviceInfoUrl in JSON-LD objects.

ServiceInfo documents are now JSON-LD documents.

TODO: rewrite schema and provide actual examples in JSON-LD.

README.md

 # ServiceInfo
 
-ServiceInfo is an effort to create a standardized way of exposing metadata about a server. This might be necessary to expose ownership and organization details, usage statistics and protocol capabilities.
+ServiceInfo is a specification for generic metadata about a web service. The specification
+provides a range of standard properties for service owners to fill to describe their
+service.
 
-## Specification
+ServiceInfo documents are [JSON-LD](https://www.w3.org/TR/json-ld/) documents. Thus additional 
+properties can be used via JSON-LD extensions by providing a context that describes the 
+properties.
 
-Please see the [specification](SPECIFICATION.md).
+ServiceInfo documents are discovered via host-meta document lookups and from other
+JSON-LD documents containing the ServiceInfo context. 
 
-## Versioning
+## Specification
 
-Current version is 1.0. Version upgrade shall happen only in backwards incompatible major changes. Forward changes, ie adding keys will not cause a version upgrading. This means implementors can be guaranteed a stable basic implementation that will not have to be changed all the time.
+Please see the [specification](SPECIFICATION.md).
 
 ## Support
 
@@ -24,14 +29,18 @@ Have a server or library you have added support to? Send a PR!
 
 ## License
 
-All content in this repository is under [CC0](http://creativecommons.org/publicdomain/zero/1.0/) unless otherwise noted.
+All content in this repository is under [CC0](http://creativecommons.org/publicdomain/zero/1.0/) 
+unless otherwise noted.
 
 ## Contributing
 
-Please open issues and pull requests if you want to suggest a change. If you open a pull request you agree for your work to be released under CC0.
+Please open issues and pull requests if you want to suggest a change. If you open a pull 
+request you agree for your work to be released under CC0.
 
 We have a [forum for discussion](https://talk.feneas.org/t/serviceinfo-specification-for-service-metadata/99).
 
 ## History
 
-ServiceInfo is a fork of [NodeInfo2](https://git.feneas.org/jaywink/nodeinfo2) which itself is a fork of [NodeInfo](https://nodeinfo.diaspora.software/) which was the successor of `statistics.json` in Diaspora.
+ServiceInfo is a fork of [NodeInfo2](https://git.feneas.org/jaywink/nodeinfo2) which itself 
+is a fork of [NodeInfo](https://nodeinfo.diaspora.software/) which was the successor of 
+`statistics.json` in Diaspora.

SPECIFICATION.md

 # ServiceInfo specification 1.0
 
+## Description
+
+ServiceInfo is a specification for generic metadata about a web service. The specification
+provides a range of standard properties for service owners to fill to describe their
+service.
+
+ServiceInfo documents are [JSON-LD](https://www.w3.org/TR/json-ld/) documents. Thus additional 
+properties can be used via JSON-LD extensions by providing a context that describes the 
+properties.
+
+ServiceInfo documents are discovered via host-meta document lookups and from other
+JSON-LD documents containing the ServiceInfo context. 
+
 ## Status
 
-This document is still in early draft status.
+This document is in early draft status.
 
 ## Definitions
 
-The term "server" in this document refers to software providing metadata about itself on a host.
+The term "service" in this document refers to a service providing metadata about itself.
 
-The term "client" in this document refers to software wishing to retrieve metadata about a host.
+The term "client" in this document refers to software wishing to retrieve metadata about 
+a service.
 
 The term "schema" refers to a schema definition provided in the schemas subdirectory.
 
-## Document location
+## Document discovery
+
+ServiceInfo documents are discovered as follows:
+
+* A `host-meta` lookup is made as per IETF [RFC6415](https://wiki.tools.ietf.org/html/rfc6415).
+  Clients MUST support the XRD representation but SHOULD also support the JRD representation. 
+
+* From the `host-meta` the client looks up a `Link` element with `rel` of 
+  `https://feneas.org/ns/serviceinfo`.
+  
+* If there are several, a client MAY choose which `Link` element they are interested by
+  looking at the `properties` of the ServiceInfo link elements in the host-meta document. 
+  
+* The client makes a GET to the `href` of the found link element. The request SHOULD be made
+  with an `Accept: application/ld+json` header.
+  
+Services MUST provide a `host-meta` as above for discovery by clients. Multiple ServiceInfo
+documents in the same host-meta SHOULD be attached a `software.name` property, to allow
+clients to choose the one they are interested in.
+
+### Host-meta examples
+
+**XRD**
+
+`GET /.well-known/host-meta`
+
+Response with content type `application/xrd+xml`:
+
+```xml
+<?xml version='1.0' encoding='UTF-8'?>
+<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'
+     xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+>
+    <Link 
+        rel='https://feneas.org/ns/serviceinfo' 
+        type='application/ld+json' 
+        href='https://domain.tld/_serviceinfo'
+    >
+        <Property type='https://feneas.org/ns/serviceinfo#software.name'>
+            Acme Service
+        </Property>
+    </Link>
+</XRD>
+```
+
+**JRD**
+
+`GET /.well-known/host-meta.json`
+
+Response with content type `application/json`:
+
+```json 
+{
+  "links": [
+    {
+      "rel": "https://feneas.org/ns/serviceinfo",
+      "type": "application/ld+json",
+      "href": "https://domain.tld/_serviceinfo",
+      "properties": {
+        "https://feneas.org/ns/serviceinfo#software.name": "Acme Service"
+      }
+    }
+  ]
+}
+```
+
+## Document location in ActivityStreams2 objects
+
+Services implementing ActivityStreams2 objects MAY have an additional context of 
+`https://feneas.org/ns/serviceinfo` indicating the presence of an URL to a ServiceInfo 
+document of the service the object is hosted at. Clients encountering objects with the 
+context MAY fetch the ServiceInfo documents.
+
+The URL to the document should be indicated as the property `serviceInfoUrl` with the correct
+context. For example:
+
+```json
+{
+  "@context": [
+    "https://www.w3.org/ns/activitystreams",
+    "https://feneas.org/ns/serviceinfo"
+  ],
+  ...
+  "serviceInfoUrl": "https://domain.tld/_serviceinfo",
+  ...
+}
+```
 
-A server SHOULD provide a ServiceInfo document at the endpoint `/.well-known/x-serviceinfo`.
+## Schema
 
-### ActivityPub
+Services MUST produce a ServiceInfo document following the 
+[JSON schema](/schemas/1.0/schema.json).
 
-Actor's in ActivityPub MAY have an additional `endpoint` called `serviceInfo`, pointing to the location of the ServiceInfo document.
+## Authors
 
-## Retrieval
+Main authors:
 
-When accessing the metadata document, a client SHOULD set the Accept header to the `application/json` media type.
+* Jason Robinson / Federated Networks Association
 
-A server SHOULD set a Content-Type of `application/json`.
+Feedback and review provided by the following people:
 
-## Schema
+* bob
+* Wiktor K (grin)
+* Hank Grabowski
+* Marius Orcsik
+* nolan
+
+ServiceInfo is based on [NodeInfo](http://nodeinfo.diaspora.software/) and 
+[NodeInfo2](https://git.feneas.org/jaywink/nodeinfo2).
 
-See the latest [schema](/schemas/1.0/schema.json).
+## License
 
-Clients SHOULD verify the ServiceInfo document against the schema.
+CC0