From defb86d5f27710f018bfb10f6caf3b2937bbf728 Mon Sep 17 00:00:00 2001
From: Lode Claassen <lode@alsvanzelf.nl>
Date: Tue, 20 Oct 2020 22:28:55 +0200
Subject: [PATCH 1/2] easily set a json schema or other describing link to the
 document

---
 src/Document.php | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/src/Document.php b/src/Document.php
index 2967cd2..935199b 100644
--- a/src/Document.php
+++ b/src/Document.php
@@ -122,6 +122,20 @@ public function setSelfLink($href, array $meta=[], $level=Document::LEVEL_ROOT)
 		$this->addLink('self', $href, $meta, $level);
 	}
 	
+	/**
+	 * set a link describing the current document
+	 * 
+	 * for example this could link to an OpenAPI or JSON Schema document
+	 * 
+	 * @note according to the spec, this can only be set to Document::LEVEL_ROOT
+	 * 
+	 * @param string $href
+	 * @param array  $meta optional, if given a LinkObject is added, otherwise a link string is added
+	 */
+	public function setDescribedByLink($href, array $meta=[]) {
+		$this->addLink('describedby', $href, $meta, $level=Document::LEVEL_ROOT);
+	}
+	
 	/**
 	 * @param string $key
 	 * @param mixed  $value

From 65ebda71f29373b37a08d42c75ebae5795fbd5c5 Mon Sep 17 00:00:00 2001
From: Lode Claassen <lode@alsvanzelf.nl>
Date: Fri, 14 May 2021 17:17:17 +0200
Subject: [PATCH 2/2] test described by root link

---
 tests/DocumentTest.php | 52 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/tests/DocumentTest.php b/tests/DocumentTest.php
index 2cd0916..e92c875 100644
--- a/tests/DocumentTest.php
+++ b/tests/DocumentTest.php
@@ -98,6 +98,58 @@ public function testAddLink_BlocksUnknownLevel() {
 		$document->addLink('foo', 'https://jsonapi.org', $meta=[], $level='foo');
 	}
 	
+	public function testSetSelfLink_HappyPath() {
+		$document = new Document();
+		
+		$array = $document->toArray();
+		$this->assertArrayNotHasKey('links', $array);
+		
+		$document->setSelfLink('https://jsonapi.org/foo');
+		
+		$array = $document->toArray();
+		$this->assertArrayHasKey('links', $array);
+		$this->assertCount(1, $array['links']);
+		$this->assertArrayHasKey('self', $array['links']);
+		$this->assertSame('https://jsonapi.org/foo', $array['links']['self']);
+	}
+	
+	public function testSetDescribedByLink_HappyPath() {
+		$document = new Document();
+		$document->setDescribedByLink('https://jsonapi.org/format', ['version' => '1.1']);
+		
+		$array = $document->toArray();
+		
+		$this->assertCount(1, $array['links']);
+		if (method_exists($this, 'assertIsArray')) {
+			$this->assertIsArray($array['links']['describedby']);
+		}
+		else {
+			$this->assertInternalType('array', $array['links']['describedby']);
+		}
+		$this->assertCount(2, $array['links']['describedby']);
+		$this->assertArrayHasKey('href', $array['links']['describedby']);
+		$this->assertArrayHasKey('meta', $array['links']['describedby']);
+		$this->assertSame('https://jsonapi.org/format', $array['links']['describedby']['href']);
+		$this->assertCount(1, $array['links']['describedby']['meta']);
+		$this->assertArrayHasKey('version', $array['links']['describedby']['meta']);
+		$this->assertSame('1.1', $array['links']['describedby']['meta']['version']);
+	}
+	
+	public function testSetDescribedByLink_WithMeta() {
+		$document = new Document();
+		
+		$array = $document->toArray();
+		$this->assertArrayNotHasKey('links', $array);
+		
+		$document->setDescribedByLink('https://jsonapi.org/format');
+		
+		$array = $document->toArray();
+		$this->assertArrayHasKey('links', $array);
+		$this->assertCount(1, $array['links']);
+		$this->assertArrayHasKey('describedby', $array['links']);
+		$this->assertSame('https://jsonapi.org/format', $array['links']['describedby']);
+	}
+	
 	public function testAddMeta_HappyPath() {
 		$document = new Document();