From 60befb77a4bb47d1feb31c3e916d828bde85e66b Mon Sep 17 00:00:00 2001
From: Abbe98 <albin.post@gmail.com>
Date: Thu, 24 Oct 2024 19:52:48 +0200
Subject: [PATCH] structured previews: first draft

---
 .../valid/example.json                        | 11 +++++
 1.0-draft/index.html                          | 44 +++++++++++++++++++
 2 files changed, 55 insertions(+)
 create mode 100644 1.0-draft/examples/structured-preview-response/valid/example.json

diff --git a/1.0-draft/examples/structured-preview-response/valid/example.json b/1.0-draft/examples/structured-preview-response/valid/example.json
new file mode 100644
index 0000000..a0a591d
--- /dev/null
+++ b/1.0-draft/examples/structured-preview-response/valid/example.json
@@ -0,0 +1,11 @@
+{
+	"id": "http://www.wikidata.org/entity/Q2",
+	"name": "Earth",
+	"description": "third planet from the Sun in the Solar System",
+	"url": "https://www.wikidata.org/wiki/Q2",
+	"image": "https://upload.wikimedia.org/wikipedia/commons/thumb/5/5b/The_Blue_Marble_%285052124705%29.jpg/330px-The_Blue_Marble_%285052124705%29.jpg",
+	"tags": [
+		["terrestrial planet", "http://www.wikidata.org/entity/Q128207"],
+		["inner planet of the Solar System", "http://www.wikidata.org/entity/Q3504248"]
+	]
+}
diff --git a/1.0-draft/index.html b/1.0-draft/index.html
index 5ef775e..ff784fb 100644
--- a/1.0-draft/index.html
+++ b/1.0-draft/index.html
@@ -54,6 +54,10 @@
             company: "National Library of Finland",
             companyURL: "https://www.kansalliskirjasto.fi/en"
           },
+          {
+            name: "Albin Larsson",
+            url: "https://byabbe.se/",
+          }
           // add yourself here!
           {
             name: "Add Yourself Here!"
@@ -700,6 +704,46 @@ <h3>Preview Queries</h3>
       </p>
       </section>
     </section>
+    <section>
+      <h2>Structured Preview Service</h2>
+      <p>
+        This section specifies how reconciliation services can provide previews of their entities in a structured format.
+      </p>
+      <section>
+        <h3>Structured Preview Endpoint</h3>
+        <p>
+          When supported, the structured preview service is queried by resolving the URI template <code>/structured-preview?id={id}</code> relative to the reconciliation endpoint, where <code>id</code> is subsituted by the <a>entity</a> identifier.
+        </p>
+      </section>
+      <section>
+        <h3>Structured Preview Responses</h3>
+        <p>
+          A response to a structured preview query must be a JSON object with the following fields describing the entity:
+          <dl>
+            <dt><code>id</code></dt>
+            <dd>The identifier of the entity;</dd>
+            <dt><code>name</code></dt>
+            <dd>Its corresponding human-readable name, to be displayed prominently to the user;</dd>
+          </dl>
+
+          The response may also contain the following optional fields:
+          <dl>
+            <dt><code>description</code></dt>
+            <dd>An optional description which can be provided to disambiguate namesakes, providing more context. This could for instance be displayed underneath the <code>name</code>;</dd>
+            <dt><code>url</code></dt>
+            <dd>An optional URL to a page with more information about the entity;</dd>
+            <dt><code>image</code></dt>
+            <dd>An optional URL to an image representing the entity;</dd>
+            <dt><code>tags</code></dt>
+            <dd>An optional list of tags and optionally an URL associated with each tag. Tags can represent entity types, categories among other things;</dd>
+          </dl>
+        </p>
+        <p>
+          For instance, a structured preview service could return the following response:
+          <pre data-include="examples/structured-preview-response/valid/example.json" class="example json"></pre>
+        </p>
+      </section>
+    </section>
     <section>
       <h2>Suggest Services</h2>
       <p>