網際網路工程任務組 G. Luff,編輯
網際網路草案
預期狀態:資訊性 K. Zyp
到期日:2017 年 8 月 26 日 SitePen(美國)
G. Court
2013

JSON 超級綱要:JSON 綱要的超文字定義
draft-luff-json-hyper-schema-00

摘要

JSON 綱要是一種基於 JSON 的格式,用於定義 JSON 數據的結構。本文檔指定了 JSON 綱要的超連結和超媒體相關關鍵字。

本備忘錄的狀態

本網際網路草案的提交完全符合 BCP 78 和 BCP 79 的規定。

網際網路草案是網際網路工程任務組 (IETF) 的工作文件。請注意,其他群組也可能將工作文件作為網際網路草案發布。目前的網際網路草案列表位於 http://datatracker.ietf.org/drafts/current/。

網際網路草案是有效期最長為六個月的草案文件,可能隨時被其他文件更新、替換或廢棄。將網際網路草案用作參考資料或將其引用為「進行中的工作」是不恰當的。

本網際網路草案將於 2017 年 8 月 26 日到期。

版權聲明

版權所有 (c) 2013 IETF Trust 及被認定為文件作者的人員。保留所有權利。

本文檔受 BCP 78 和 IETF 信託關於 IETF 文件之法律條款 (http://trustee.ietf.org/license-info) 的約束,該條款於本文檔發布之日生效。請仔細閱讀這些文件,因為它們描述了您對於本文檔的權利和限制。從本文檔中提取的程式碼元件必須包含信託法律條款第 4.e 節中描述的簡化 BSD 授權文字,並且按簡化 BSD 授權中的描述提供,不提供任何保證。


目錄

1. 簡介

JSON 綱要是一種基於 JSON 的格式,用於定義 JSON 數據的結構。本文檔指定了 JSON 綱要的超連結和超媒體相關關鍵字。

術語 JSON 超級綱要用於指使用這些關鍵字的 JSON 綱要。

本規範將使用 JSON 綱要核心規範 [json-schema-core] 定義的術語。建議讀者備有一份本規範的副本。

2. 慣例和術語

本文檔中的關鍵字「必須 (MUST)」、「不得 (MUST NOT)」、「必要 (REQUIRED)」、「應 (SHALL)」、「不應 (SHALL NOT)」、「應該 (SHOULD)」、「不應該 (SHOULD NOT)」、「建議 (RECOMMENDED)」、「可以 (MAY)」和「可選 (OPTIONAL)」應按照 RFC 2119 [RFC2119] 中的描述進行解釋。

術語「綱要 (schema)」、「實例 (instance)」、「屬性 (property)」和「項目 (item)」應按照 JSON 綱要核心規範 [json-schema-core] 中的定義進行解釋。

3. 概述

本文檔描述如何使用 JSON 綱要來定義實例數據的超連結。它還定義了如何提供將 JSON 數據解釋為豐富多媒體文檔所需的其他資訊。

與核心 JSON 綱要關鍵字一樣,「綱要關鍵字」部分中描述的所有關鍵字都是可選的。

這是一個範例 JSON 綱要,定義了超連結,並為「imgData」屬性提供了多媒體解釋

{
    "title": "Written Article",
    "type": "object",
    "properties": {
        "id": {
            "title": "Article Identifier",
            "type": "number"
        },
        "title": {
            "title": "Article Title",
            "type": "string"
        },
        "authorId": {
            "type": "integer"
        },
        "imgData": {
            "title": "Article Illustration (small)",
            "type": "string",
            "media": {
                "binaryEncoding": "base64",
                "type": "image/png"
            }
        }
    },
    "required" : ["id", "title", "authorId"],
    "links": [
        {
            "rel": "full",
            "href": "{id}"
        },
        {
            "rel": "author",
            "href": "/user?id={authorId}"
        }
    ]
}

                

此範例綱要定義了實例的屬性。對於「imgData」屬性,它指定應將其進行 base64 解碼,並將產生的二進制數據視為 PNG 圖像。它還定義了實例的連結關係,URI 包含實例的值。

上述綱要描述的 JSON 實例範例可能是

{
    "id": 15,
    "title": "Example data",
    "authorId": 105,
    "imgData": "iVBORw...kJggg=="
}

                

為了便於閱讀,base-64 數據已縮寫。

3.1. 設計考量

本文檔的目的是定義 JSON 綱要的關鍵字,允許將 JSON 數據理解為超文字。

JSON 數據本身需要客戶端具有有關格式的特殊知識,才能解釋為超文字。本文檔提出了一種描述此類 JSON 格式的超文字和超媒體解釋的方法,而無需定義保留的關鍵字或以其他方式限制 JSON 數據的結構。

4. 綱要關鍵字

4.1. 連結

綱要的「連結」屬性用於將連結描述物件與實例關聯。此屬性的值必須是一個陣列,且陣列中的項目必須是連結描述物件,如下所述。

使用「連結」關鍵字的範例綱要可能是

{
    "title": "Schema defining links",
    "links": [
        {
            "rel": "full",
            "href": "{id}"
        },
        {
            "rel": "parent",
            "href": "{parent}"
        }
    ]
}
                    

4.1.1. 每個 URI 的多個連結

單個 URI 可能在與實例的關係中具有多個角色。這不是問題 - 同一個 URI 可以在多個連結描述物件中使用。

例如,此綱要描述了通過 HTTP 存取的部落格文章的格式。這些連結描述瞭如何存取文章的評論、如何搜尋評論以及如何提交新評論,所有這些都使用相同的 URI

{
    "title": "News post",
    ...
    "links": [
        {
            "rel": "comments",
            "href": "/{id}/comments"
        },
        {
            "rel": "search",
            "href": "/{id}/comments",
            "schema": {
                "type": "object",
                "properties": {
                    "searchTerm": {
                        "type": "string"
                    },
                    "itemsPerPage": {
                        "type": "integer",
                        "minimum": 10,
                        "multipleOf": 10,
                        "default": 20
                    }
                },
                "required": ["searchTerm"]
            }
        },
        {
            "title": "Post a comment",
            "rel": "create",
            "href": "/{id}/comments",
            "method": "POST",
            "schema": {
                "type": "object",
                "properties": {
                    "message": {
                        "type": "string"
                    }
                },
                "required": ["message"]
            }
        }
    ]
}
                        

如果客戶端遵循第一個連結,則 URI 可能會擴展為「/15/comments」。對於第二個連結,方法是「GET」(HTTP 的預設值),因此遵循此連結的客戶端會將參數添加到 URL 中,以產生類似「/15/comments?searchTerm=JSON&itemsPerPage=50」的內容。第三個連結定義了客戶端可能將 POST 發送到 URI(例如「/15/comments」)的可能互動,其中 post-data 是新評論的 JSON 表示形式,例如

{
    "message": "This is an example comment"
}
                        

4.2. 片段解析

當定址 JSON 文檔時,URI 的片段部分可用於引用文檔中的特定實例。

此關鍵字指示用於在給定片段部分的情況下,在文檔中尋找適當實例的方法。預設片段解析協定是「json-pointer」,如下所述。可以使用其他片段解析協定,但本文檔中未定義這些協定。

如果實例由提供「根」關係連結的綱要描述,或通過 HTTP 連結標頭 [RFC5988] 提供此類連結,則應將「根」連結的目標視為所有使用文檔結構(例如「json-pointer」)的片段解析方法的文檔根目錄。唯一的例外是「根」連結本身的解析。

4.2.1. json-pointer 片段解析

「json-pointer」片段解析協定使用 JSON 指標 [json-pointer] 來解析實例表示形式中 URI 的片段識別碼。

4.3. 媒體

「媒體」屬性表示此實例包含編碼在 JSON 字串中的非 JSON 數據。它描述了內容的類型以及編碼方式。

此屬性的值必須是一個物件,且對於任何非字串的實例,應忽略此屬性。

4.3.1. 「媒體」的屬性

「媒體」關鍵字的值可能包含以下任何屬性

4.3.1.1. 二進制編碼

如果實例值為字串,則此屬性定義應將該字串解釋為二進制數據,並使用此屬性命名的編碼進行解碼。RFC 2045, Sec 6.1 [RFC2045] 列出了此屬性的可能值。

4.3.1.2. 類型

此屬性的值必須是 RFC 2046 [RFC2046] 定義的媒體類型。此屬性定義了此綱要定義的實例的媒體類型。

如果未設定「二進制編碼」屬性,但實例值為字串,則此屬性的值應指定文字文檔類型,並且字元集應為 JSON 字串值解碼成的字元集(預設值為 Unicode)。

4.3.2. 範例

這是一個範例綱要,說明了「媒體」的使用

{
    "type": "string",
    "media": {
        "binaryEncoding": "base64",
        "type": "image/png"
    }
}

                        

此綱要描述的實例應該是字串,並且它們的值應該可以解釋為 base64 編碼的 PNG 圖像。

另一個範例

{
    "type": "string",
    "media": {
        "mediaType": "text/html"
    }
}

                        

此綱要描述的實例應該是包含 HTML 的字串,使用 JSON 字串解碼成的任何字元集(預設值為 Unicode)。

4.4. 唯讀

如果此關鍵字的值為布林值 true,則表示不應變更實例屬性,且用戶代理嘗試修改此屬性值的行為預計會被伺服器拒絕。

此關鍵字的值必須是布林值。預設值為 false。

4.5. 路徑起點

此屬性是一個 URI,定義為了驗證,實例的 URI 必須以此 URI 開頭。「路徑起點」屬性的值必須使用 RFC 3986, Sec 5 [RFC3986] 中的規則,相對於最接近的 URI 解析範圍(如 JSON 綱要核心規範 [json-schema-core] 中定義)進行解析。

當為實例引用多個綱要時,用戶代理可以通過確定實例的 URI 是否以「路徑起點」屬性的值開頭,來判斷此綱是否適用於特定實例。如果實例的 URI 不是以此 URI 開頭,或者如果另一個綱要指定了更長且也與實例匹配的起始 URI,則不應將此綱要視為描述實例。任何沒有 pathStart 屬性的綱要都應被視為適用於其引用的所有實例。

5. 連結描述物件

連結描述物件 (LDO) 用於描述單個連結關係。在綱要的上下文中,它定義了綱要實例的連結關係,並且可以由實例值參數化。連結描述物件 (LDO) 必須是一個物件。

可以在不使用 JSON 綱要的情況下使用連結描述格式,並且可以通過將規範性連結描述綱要引用為使用連結的數據結構的綱要來聲明此格式的使用。規範性連結描述綱要的 URI 為:https://json-schema.dev.org.tw/links (最新版本) 或 https://json-schema.dev.org.tw/draft-04/links (draft-04 版本)。

可以使用「綱要」關鍵字定義類似「表單」的功能,該關鍵字提供了一個綱要,用於描述要提供給伺服器的數據。

5.1. href

「href」連結描述屬性的值是一個範本,用於決定相關資源的目標 URI。實例屬性的值應該依照 RFC 3986 [RFC3986] 解析為 URI 參考,並且可以是相對於 URI 的相對參考。用於相對 URI 解析的基礎 URI 應該是用於檢索實例物件的 URI(而非 schema)。

用於相對 URI 解析的基礎 URI 應該定義如下:

此屬性不是可選的。

5.1.1. URI 範本化

「href」的值應作為 URI 範本使用,如 RFC 6570 [RFC6570] 中所定義。但是,適用一些特殊考量:

5.1.1.1. 預處理

URI 範本規範 [RFC6570] 限制了變數名稱可用的字元集。但是,JSON 中的屬性名稱可以是任何 UTF-8 字串。

為了允許在範本中使用任何 JSON 屬性名稱,在使用「href」的值作為 URI 範本之前,必須按順序套用以下預處理規則:

5.1.1.1.1. 括號跳脫

此步驟的目的是允許使用括號來對大括號內的變數名稱進行百分比編碼。要跳脫的變數名稱被括在圓括號內,右圓括號字元「)」會跳脫為一對右圓括號「))」。由於空字串在 RFC 6570 中不是有效的變數名稱,因此空的括號對會被替換為「%65mpty」。

規則如下:

找到文本中最大的可能區段,使得:

必須根據以下規則替換這些文本區段的每一個(包括周圍的圓括號):

5.1.1.1.2. 替換 $

在以上替換之後,如果字元「$」(美元符號)出現在一對大括號內,則必須將其替換為文字「%73elf」(即「self」帶有百分比編碼的「s」)。

此階段的目的是允許在 URI 範本中使用實例值本身(而不是其物件屬性或陣列項目),方法是使用特殊值「%73elf」。

5.1.1.1.3. 特殊情況值的選擇

之所以選擇「%73elf」和「%65mpty」的特殊情況值,是因為它們不太可能被人類或自動跳脫意外生成。

5.1.1.1.4. 範例

例如,以下是一些「href」的可能值,以及預處理後的結果:

{% raw %}
Input                    Output
-----------------------------------------
"no change"              "no change"
"(no change)"            "(no change)"
"{(escape space)}"       "{escape%20space}"
"{(escape+plus)}"        "{escape%2Bplus}"
"{(escape*asterisk)}"    "{escape%2Aasterisk}"
"{(escape(bracket)}"     "{escape%28bracket}"
"{(escape))bracket)}"    "{escape%29bracket}"
"{(a))b)}"             "{a%29b}
"{(a (b)))}"             "{a%20%28b%29}
"{()}"                   "{%65mpty}
"{+$*}"                   "{+%73elf*}
"{+($)*}"                 "{+%24*}
{% endraw %}
                                    

請注意,在最後一個範例中,由於「+」位於括號之外,因此它保持未跳脫,而在第四個範例中,「+」被跳脫。

5.1.1.2. 替換的值

預處理後,將使用實例中的資料填入 URI 範本。為了允許使用任何物件屬性(包括空字串)、陣列索引或實例值本身,定義了以下規則:

對於 URI 範本中的給定變數名稱,要使用的值確定如下:

5.1.1.2.1. 轉換為字串

當 URI 範本引用的任何值為 null、布林值或數字時,應首先將其轉換為字串,如下所示:

在某些軟體環境中,數字的原始 JSON 表示形式將不可用(無法區分 1.0 和 1),因此應使用任何合理的表示形式。Schema 和 API 作者應牢記這一點,並且在確切表示形式很重要時,請使用其他類型(例如字串或布林值)。

5.1.1.3. 遺失的值

有時,適當的值將不可用。例如,範本可能會指定使用物件屬性,但實例是陣列或字串。

如果範本所需的任何值不存在於 JSON 實例中,則可以從其他來源(例如預設值)提供替代值。否則,該連結定義應該被視為不適用於該實例。

5.2. rel

「rel」屬性的值表示目標資源的關係名稱。此屬性不是可選的。

應該將與目標的關係理解為明確地來自 Schema(或子 Schema)所應用於的實例物件,而不僅僅是包含物件的階層中的頂層資源。從頂層資源到目標的連結關係必須使用描述頂層 JSON 表示形式的 Schema 來指示。

關係定義不應依賴於媒體類型,並且鼓勵使用者利用現有的已接受關係定義,包括現有關係註冊表中的關係定義(請參閱 RFC 4287 [RFC4287])。但是,為了清楚了解 JSON Schema 定義的關係中規範性解釋,我們在此處定義了這些關係:

self
如果關係值是「self」,則當在實例物件中遇到此屬性時,該物件表示一個資源,並且該實例物件被視為指定 URI 所識別的目標資源的完整表示形式。
full
這表示該連結的目標是實例物件的完整表示形式。包含此連結的實例可能不是完整表示形式。
describedBy
這表示該連結的目標是一個描述實例物件的 Schema。這可以用於明確表示 JSON 物件階層中物件的 Schema,從而促進多型別資料結構。
root
此關係表示該連結的目標應該被視為使用者代理互動或片段解析的表示形式的根或主體。文件中所有其他資料都可以視為該文件的元資料。此連結的 URI 必須參考實例文件中的位置,否則必須忽略該連結。

如果不需要使用實例中的資料進行參數化,則以下關係適用於 Schema(Schema 作為關係中的「來源」資源):

instances
這表示代表 Schema 實例集合的目標資源。
create
這表示用於建立 Schema 新實例的目標。此連結定義應該是一個具有非安全方法(例如 POST)的提交連結。

例如,如果定義了 Schema:

{
    "links": [{
        "rel": "self",
        "href": "{id}"
    }, {
        "rel": "up",
        "href": "{upId}"
    }, {
        "rel": "children",
        "href": "?upId={id}"
    }]
}
                    

如果使用 JSON 表示形式檢索實例資源集合:

GET /Resource/

[{
    "id": "thing",
    "upId": "parent"
}, {
    "id": "thing2",
    "upId": "parent"
}]
                    

這會表示對於集合中的第一個項目,其自身的 (self) URI 會解析為「/Resource/thing」,並且第一個項目的「up」關係應該解析為「/Resource/parent」中的資源。「children」集合將位於「/Resource/?upId=thing」。

請注意,這些關係值不區分大小寫,與它們在 HTML 和 HTTP 連結標頭 [RFC5988] 中的使用一致。

5.2.1. 使用「root」連結進行片段解析

存在關係為「root」的連結會改變文件根的認定。對於瀏覽文件的方法(例如 JSON 指標片段),「root」連結的目標應該是此類方法的起點。

唯一的例外是「root」連結本身。在計算關係為「root」的連結的目標時,不得將現有的「root」連結納入考量。

例如,假設我們有以下 Schema:

{
    "links": [{
        "rel": "root",
        "href": "#/myRootData"
    }]
}
                            

以及從 URI「http://example.com/data/12345」返回的以下資料:

{
    "myRootData": {
        "title": "Document title"
    },
    "metaData": {
        ...
    }
}
                            
URI                                         Data
-----------------------------------------------------------------------
http://example.com/data/12345               {"title": "Document title"}
http://example.com/data/12345#/title        "Document title"

                            

為了正確解析 URL「http://example.com/data/12345」,我們必須考慮「root」連結。以下是一些範例 URI,以及它們將解析為的資料:

5.2.2. 「self」連結的安全性考量

當使用 "self" 連結關係來表示物件的完整呈現時,如果目標 URI 並不等於或不是包含 "self" 連結的資源呈現所使用的請求 URI 的子路徑,則使用者代理程式「不應該」將該呈現視為目標 URI 所表示資源的權威性呈現。

例如,如果定義了一個超綱要 (hyper schema):

{
    "links": [{
        "rel": "self",
        "href": "{id}"
    }]
}
                            

且從 somesite.com 請求了一個資源:

GET /foo/

                            

並收到以下回應:

Content-Type: application/json; profile=/schema-for-this-data

[{
    "id": "bar",
    "name": "This representation can be safely treated \
        as authoritative "
}, {
    "id": "/baz",
    "name": "This representation should not be treated as \
        authoritative the user agent should make request the resource\
        from '/baz' to ensure it has the authoritative representation"
}, {
    "id": "http://othersite.com/something",
    "name": "This representation\
        should also not be treated as authoritative and the target\
        resource representation should be retrieved for the\
        authoritative representation"
}]
                            

5.3. 標題

此屬性定義連結的標題。值必須為字串。

使用者代理程式「可以」在向使用者呈現連結時使用此標題。

5.4. targetSchema

此屬性值僅供參考,是一個綱要,定義了如果連結的目標使用 JSON 呈現返回時,連結目標的 JSON 呈現的預期結構。

5.4.1. "targetSchema" 的安全性考量

此屬性具有與 "mediaType" 類似的安全性問題。客戶端「絕對不能」使用此屬性的值來協助解讀在跟隨連結後收到的回應資料,因為這會使「安全」的資料容易被重新解讀。

例如,假設有兩位程式設計師正在使用僅限文字的留言板討論網路安全。以下是該對話中的一些資料,其 URI 為:http://forum.example.com/topics/152/comments/13

{
    "topicId": 152,
    "commentId": 13,
    "from": {
        "name": "Jane",
        "id": 5
    },
    "to": {
        "name": "Jason",
        "id": 8
    },
    "message": "It's easy, you just add some HTML like
                  this: <script>doSomethingEvil()</script>"
}
                            

為了方便閱讀,訊息字串被分成兩行。

{
    "rel": "evil-attack",
    "href": "http://forum.example.com/topics/152/comments/13",
    "targetSchema": {
        "properties": {
            "message": {
                "description": "Re-interpret the message text as HTML",
                "media": {
                    "type": "text/html"
                }
            }
        }
    }
}
                            

第三方可能會在另一個位置提供以下連結描述物件:

如果客戶端在解讀上述資料時使用了此 "targetSchema" 值,則可能會將 "message" 的內容顯示為 HTML。此時,嵌入在訊息中的 JavaScript 可能會被執行 (在 "forum.example.com" 網域的環境中)。

5.5. mediaType

此屬性的值僅供參考,表示預期在提取此資源時返回的媒體類型 RFC 2046 [RFC2046]。此屬性值「可以」改為使用 RFC 2161 第 14.1 節 - HTTP "Accept" 標頭 [RFC2616] 中定義的相同模式,作為媒體範圍。

此屬性類似於 HTML 中 <a> 元素的 "type" 屬性 (建議的內容類型),或 HTTP Link 標頭 [RFC5988] 中的 "type" 參數。使用者代理程式「可以」使用此資訊來通知使用者在跟隨連結之前所呈現的介面,但此資訊「絕對不能」用於解讀產生的資料。在決定如何解讀透過跟隨此連結取得的資料時,無論此屬性的值為何,使用者代理程式的行為都「必須」相同。

如果指定了此屬性的值,並且連結的目標將使用任何支援 HTTP/1.1 "Accept" 標頭 RFC 2616 第 14.1 節 [RFC2616] 的協定來取得,則使用者代理程式「可以」使用此屬性的值來協助在向伺服器發出請求時組裝該標頭。

如果未指定此屬性的值,則該值應被視為 "application/json"。

例如,如果定義了 Schema:

{
    "links": [{
        "rel": "self",
        "href": "/{id}/json"
    }, {
        "rel": "alternate",
        "href": "/{id}/html",
        "mediaType": "text/html"
    }, {
        "rel": "alternate",
        "href": "/{id}/rss",
        "mediaType": "application/rss+xml"
    }, {
        "rel": "icon",
        "href": "{id}/icon",
        "mediaType": "image/*"
    }]
}

                    

此綱要描述的合適實例將定義四個連結。 "rel" 值為 "self" 的連結將具有預期的 MIME 類型 "application/json" (預設值)。 "rel" 值為 "alternate" 的兩個連結指定了目前項目的 HTML 和 RSS 版本的位址。 "rel" 值為 "icon" 的連結指向一個圖像,但未指定確切的格式。

從以上範例顯示項目的視覺使用者代理程式可能會呈現一個代表 RSS 饋送的按鈕,按下該按鈕時,會將目標 URI (計算出的 "href" 值) 傳遞給更適合顯示它的視圖,例如新聞饋送聚合器索引標籤。

請注意,以上述方式呈現連結,或將 URI 傳遞給新聞饋送聚合器視圖,並不構成資料的解讀,而是對連結的解讀。資料本身的解讀由新聞饋送聚合器執行,該聚合器「應該」拒絕任何如果顯示在主視圖中,也不會被解讀為新聞饋送的資料。

5.5.1. "mediaType" 的安全性考量

連結定義中的 "mediaType" 屬性定義了連結目標的預期格式。但是,這僅供參考,且「絕對不能」被視為權威性資訊。

在選擇如何解讀資料時,伺服器提供的類型資訊 (或從檔名推斷的類型資訊,或任何其他常用方法) 「必須」是唯一的考量因素,並且「絕對不能」使用連結的 "mediaType" 屬性。使用者代理程式「可以」使用此資訊來確定它們如何呈現連結或在何處顯示連結 (例如,懸停文字、在新索引標籤中開啟)。如果使用者代理程式決定將連結傳遞給外部程式,則它們「應該」首先驗證資料是否為通常會傳遞給該外部程式的類型。

這是為了防止重新解讀「安全」的資料,類似於 "targetSchema" 的預防措施。

5.6. 提交連結屬性

以下屬性也適用於連結描述物件,並提供類似於 HTML 表單的功能,以提供一種將額外 (通常是使用者提供的) 資訊提交給伺服器的方法。

5.6.1. method

此屬性定義可以使用哪種方法來存取目標資源。在 HTTP 環境中,這可能是 "GET" 或 "POST" (或其他 HTTP 方法)。

某些連結關係值暗示了一組適用於該連結的 HTTP 方法。例如,客戶端可能會假設具有 "edit" 關係的連結可以與 "PUT" HTTP 方法結合使用。如果客戶端不知道哪些方法可能適用,則此值「應該」預設為 "GET"。

5.6.2. encType

如果存在,此屬性表示伺服器支援的查詢媒體類型格式,用於查詢或發佈到目標資源中的實例集合。查詢可以附加到目標 URI,以使用基於屬性的限制來查詢集合,這些限制應該從伺服器返回或用於將資料發佈到資源 (取決於方法)。

例如,對於以下綱要:

{
    "links": [{
        "encType": "application/x-www-form-urlencoded",
        "method": "GET",
        "href": "/Product/",
        "properties": {
            "name": {
                "description": "name of the product"
            }
        }
    }]
}
                            

這表示客戶端可以查詢伺服器,以取得具有特定名稱的實例。

例如:

/Product/?name=Slinky

                            

5.6.3. schema

此屬性包含一個綱要,該綱要定義了提交請求的可接受結構。對於 GET 請求,此綱要將定義查詢字串的屬性,而對於 POST 請求,此綱要將定義主體。

請注意,這與 "href" 的 URI 範本 (使用來自實例的資料,而不是使用者提交的資料) 是分開的。它也與 "targetSchema" 屬性分開,該屬性為客戶端在跟隨連結時應該期望返回的資料提供了一個綱要。

6. IANA 考量事項

6.1. 連結關係註冊

此註冊表由 IANA 根據 RFC 4287 [RFC4287] 維護,此規範新增了四個值:"full"、"create"、"instances"、"root"。新的分配須經 IESG 批准,如 RFC 5226 [RFC5226] 中所述。應透過電子郵件向 IANA 提出請求,然後 IANA 會將請求轉發給 IESG,請求批准。

7. 參考資料

7.1. 標準參考資料

[RFC2045] Freed, N.N. Borenstein,"多用途網際網路郵件擴充 (MIME) 第一部分:網際網路訊息本文格式",RFC 2045,DOI 10.17487/RFC2045,1996 年 11 月。
[RFC2119] Bradner, S.,"在 RFC 中用於指示需求級別的關鍵字",BCP 14,RFC 2119,DOI 10.17487/RFC2119,1997 年 3 月。
[RFC3986] Berners-Lee, T.Fielding, R.L. Masinter,"統一資源識別符 (URI):通用語法",STD 66,RFC 3986,DOI 10.17487/RFC3986,2005 年 1 月。
[RFC4287] Nottingham, M.R. Sayre,"Atom 聯合格式",RFC 4287,DOI 10.17487/RFC4287,2005 年 12 月。
[RFC6570] Gregorio, J.Fielding, R.Hadley, M.Nottingham, M.D. Orchard,"URI 範本",RFC 6570,DOI 10.17487/RFC6570,2012 年 3 月。
[json-pointer] Bryan, P.Zyp, K.M. Nottingham,"JSON 指標",2012 年 8 月。
[json-schema-core] Galiegue, F.Zyp, K.G. Court,"JSON 綱要:核心定義和術語",2013 年。

7.2. 資訊性參考資料

[RFC2616] Fielding, R.Gettys, J.Mogul, J.Frystyk, H.Masinter, L.Leach, P.T. Berners-Lee,"超文字傳輸協定 -- HTTP/1.1",RFC 2616,DOI 10.17487/RFC2616,1999 年 6 月。
[RFC5226] Narten, T.H. Alvestrand,"在 RFC 中撰寫 IANA 考量事項章節的指南",BCP 26,RFC 5226,DOI 10.17487/RFC5226,2008 年 5 月。
[RFC2046] Freed, N.N. Borenstein,"多用途網際網路郵件擴充 (MIME) 第二部分:媒體類型",RFC 2046,DOI 10.17487/RFC2046,1996 年 11 月。
[RFC5988] Nottingham, M.,"Web 連結",RFC 5988,DOI 10.17487/RFC5988,2010 年 10 月。
[W3C.REC-html401-19991224] Raggett, D.Hors, A.I. Jacobs,"HTML 4.01 規範",全球資訊網協會建議 REC-html401-19991224,1999 年 12 月。

附錄 A. 變更日誌

草案-04

草案-03

草案-02

草案-01

草案-00

作者地址

Geraint Luff (編輯) 劍橋, 英國 電子郵件: [email protected]
Kris Zyp SitePen (美國) 530 Lytton Avenue 帕羅奧圖, CA 94301, 美國 電話: +1 650 968 8787 電子郵件: [email protected]
Gary Court 卡加利, AB, 加拿大 電子郵件: [email protected]