<div id="readability-page-1" class="page"><div><h2 id="51-top-level">5.1. 최상위 (Top Level)</h2>
<hr>
JSON 오브젝트는 데이터를 포함한 JSON API 요청과 응답에 대한 근본(root) 입니다. &lt;MUST&gt; 이 오브젝트를 문서의 “최상위”라 정의합니다.
<blockquote>
A JSON object MUST be at the root of every JSON API request and response containing data. This object defines a document’s “top level”.
</blockquote>
문서에서는 최소한 다음 최상위 멤버중 하나를 포함해야 합니다 &lt;MUST&gt;:
<ul>
<li><code>data</code>: 문서에서 “일차 데이터”</li>
<li><code>errors</code>: <a href="http://jsonapi.org/format/#errors">error objects</a> 에대한 배열</li>
<li><code>meta</code>: 비표준 메타 정보가 포함되어있는 <a href="http://jsonapi.org/format/#document-meta">meta object</a>.</li>
</ul>
<blockquote>
A document MUST contain at least one of the following top-level members:
<ul>
<li><code>data</code>: the document’s “primary data”</li>
<li>​<code>errors</code>: an array of <a href="http://jsonapi.org/format/#errors">error objects</a></li>
<li><code>meta</code>: a <a href="http://jsonapi.org/format/#document-meta">meta object</a> that contains non-standard meta-information.</li>
</ul>
</blockquote>
<code>data</code>와 <code>errors</code> 멤버는 동일한 문서에 공존할 수 없습니다. &lt;MUST NOT&gt;
<blockquote>
The members <code>data</code> and <code>errors</code> MUST NOT coexist in the same document.
</blockquote>
문서에서는 다음 내용과 같은 최상위 멤버가 포함될 수 있습니다 &lt;MAY&gt;:
<ul>
<li><code>jsonapi</code>: 서버에서 구현을 기술하는 오브젝트</li>
<li><code>links</code>: <a href="http://jsonapi.org/format/#document-links">links object</a>는 일차 데이터와 연결됩니다.</li>
<li><code>included</code>: 포함된 리소스중 각기 다르거나 일차 데이터와 관련된 <a href="http://jsonapi.org/format/#document-resource-objects">resource objects</a>에 대한 배열.</li>
</ul>
<blockquote>
A document MAY contain any of these top-level members:
<ul>
<li><code>jsonapi</code>: an object describing the server’s implementation</li>
<li><code>links</code>: a <a href="http://jsonapi.org/format/#document-links">links object</a> related to the primary data.</li>
<li><code>included</code>: an array of <a href="http://jsonapi.org/format/#document-resource-objects">resource objects</a> that are related to the primary data and/or each other (“included resources”).</li>
</ul>
</blockquote>
문서에 최상위 <code>data</code> 키가 포함되지 않은 경우, <code>included</code> 멤버 중 하나에 존재할 수 없습니다. &lt;MUST NOT&gt;
<blockquote>
If a document does not contain a top-level <code>data</code> key, the <code>included</code> member MUST NOT be present either.
</blockquote>
최상위 <a href="http://jsonapi.org/format/#document-links">links object</a>는 다음 맴버를 포함할 수 있습니다 &lt;MAY&gt;:
<ul>
<li><code>self</code>: 현재 응답 문서를 생성한 <a href="http://jsonapi.org/format/#document-links">link</a>.</li>
<li><code>related</code>: 일차 데이터와 리소스간 관계를 나타내는 <a href="http://jsonapi.org/format/#document-resource-object-related-resource-links">related resource link</a>.</li>
<li>일차 데이터에 대한 <a href="http://jsonapi.org/format/#fetching-pagination">pagination</a> 링크.</li>
</ul>
<blockquote>
The top-level <a href="http://jsonapi.org/format/#document-links">links object</a> MAY contain the following members:
<ul>
<li><code>self</code>: the <a href="http://jsonapi.org/format/#document-links">link</a> that generated the current response document.</li>
<li><code>related</code>: a <a href="http://jsonapi.org/format/#document-resource-object-related-resource-links">related resource link</a> when the primary data represents a resource relationship.</li>
<li><a href="http://jsonapi.org/format/#fetching-pagination">pagination</a> links for the primary data.</li>
</ul>
</blockquote>
문서에서 “일차 데이터”는 요청에의해 대상이되는 자원의 컬렉션이나 자원 관계를 나타냅니다.
<blockquote>
The document’s “primary data” is a representation of the resource or collection of resources targeted by a request.
</blockquote>
일차 데이터는 다음 중 하나 입니다 &lt;MUST&gt;:
<ul>
<li>단일 자원을 대상으로 요구하는 단일 <a href="http://jsonapi.org/format/#document-resource-objects">resource object</a>, 단일 <a href="http://jsonapi.org/format/#document-resource-identifier-objects">resource identifier object</a>, <code>null</code>을 나타냅니다.</li>
<li>타겟 리소스 컬렉션 요청에 대한 <a href="http://jsonapi.org/format/#document-resource-objects">resource objects</a> 배열, <a href="http://jsonapi.org/format/#document-resource-identifier-objects">resource identifier objects</a> 배열, 빈 배열 (<code>[]</code>)를 나타냅니다.</li>
</ul>
<blockquote>
Primary data MUST be either:
<ul>
<li>a single <a href="http://jsonapi.org/format/#document-resource-objects">resource object</a>, a single <a href="http://jsonapi.org/format/#document-resource-identifier-objects">resource identifier object</a>, or <code>null</code>, for requests that target single resources</li>
<li>an array of <a href="http://jsonapi.org/format/#document-resource-objects">resource objects</a>, an array of <a href="http://jsonapi.org/format/#document-resource-identifier-objects">resource identifier objects</a>, or an empty array (<code>[]</code>), for requests that target resource collections</li>
</ul>
</blockquote>
예를 들어, 다음 일차 데이터는 단일 리소스 오브젝트를 나타냅니다:
<blockquote>
For example, the following primary data is a single resource object:
</blockquote>
<div><pre><code>{
 "data": {
 "type": "articles",
 "id": "1",
 "attributes": {
 // ... this article's attributes
 },
 "relationships": {
 // ... this article's relationships
 }
 }
}
</code></pre></div>


다음 일차 데이터는 동일한 리소스를 참조하는 단일 <a href="http://jsonapi.org/format/#document-resource-identifier-objects">resource identifier object</a>입니다:
<blockquote>
The following primary data is a single <a href="http://jsonapi.org/format/#document-resource-identifier-objects">resource identifier object</a> that references the same resource:
</blockquote>
<div><pre><code>{
 "data": {
 "type": "articles",
 "id": "1"
 }
}
</code></pre></div>


리소스에 대한 논리 컬렉션은 아이템 하나만 있거나 비어있더라도 배열로 표현합니다. &lt;MUST&gt;
<blockquote>
A logical collection of resources MUST be represented as an array, even if it only contains one item or is empty.
</blockquote></div></div>

잘 밤에 쓸데없는 생각하기...

Thomas Sungjin Kang

5.1. 최상위 (Top Level)
JSON 오브젝트는 데이터를 포함한 JSON API 요청과 응답에 대한 근본(root) 입니다. <MUST> 이 오브젝트를 문서의 “최상위”라 정의합니다.
A JSON object MUST be at the root of every JSON API request and response containing data. This object defines a document’s “top level”.
문서에서는 최소한 다음 최상위 멤버중 하나를 포함해야 합니다 <MUST>:
data: 문서에서 “일차 데이터”
errors: error objects 에대한 배열
meta: 비표준 메타 정보가 포함되어있는 meta object.
A document MUST contain at least one of the following top-level members:
data: the document’s “primary data”
​errors: an array of error objects
meta: a meta object that contains non-standard meta-information.
data와 errors 멤버는 동일한 문서에 공존할 수 없습니다. <MUST NOT>
The members data and errors MUST NOT coexist in the same document.
문서에서는 다음 내용과 같은 최상위 멤버가 포함될 수 있습니다 <MAY>:
jsonapi: 서버에서 구현을 기술하는 오브젝트
links: links object는 일차 데이터와 연결됩니다.
included: 포함된 리소스중 각기 다르거나 일차 데이터와 관련된 resource objects에 대한 배열.
A document MAY contain any of these top-level members:
jsonapi: an object describing the server’s implementation
links: a links object related to the primary data.
included: an array of resource objects that are related to the primary data and/or each other (“included resources”).
문서에 최상위 data 키가 포함되지 않은 경우, included 멤버 중 하나에 존재할 수 없습니다. <MUST NOT>
If a document does not contain a top-level data key, the included member MUST NOT be present either.
최상위 links object는 다음 맴버를 포함할 수 있습니다 <MAY>:
self: 현재 응답 문서를 생성한 link.
related: 일차 데이터와 리소스간 관계를 나타내는 related resource link.
일차 데이터에 대한 pagination 링크.
The top-level links object MAY contain the following members:
self: the link that generated the current response document.
related: a related resource link when the primary data represents a resource relationship.
pagination links for the primary data.
문서에서 “일차 데이터”는 요청에의해 대상이되는 자원의 컬렉션이나 자원 관계를 나타냅니다.
The document’s “primary data” is a representation of the resource or collection of resources targeted by a request.
일차 데이터는 다음 중 하나 입니다 <MUST>:
단일 자원을 대상으로 요구하는 단일 resource object, 단일 resource identifier object, null을 나타냅니다.
타겟 리소스 컬렉션 요청에 대한 resource objects 배열, resource identifier objects 배열, 빈 배열 ([])를 나타냅니다.
Primary data MUST be either:
a single resource object, a single resource identifier object, or null, for requests that target single resources
an array of resource objects, an array of resource identifier objects, or an empty array ([]), for requests that target resource collections
예를 들어, 다음 일차 데이터는 단일 리소스 오브젝트를 나타냅니다:
For example, the following primary data is a single resource object:
{
 "data": {
 "type": "articles",
 "id": "1",
 "attributes": {
 // ... this article's attributes
 },
 "relationships": {
 // ... this article's relationships
 }
 }
}
다음 일차 데이터는 동일한 리소스를 참조하는 단일 resource identifier object입니다:
The following primary data is a single resource identifier object that references the same resource:
{
 "data": {
 "type": "articles",
 "id": "1"
 }
}
리소스에 대한 논리 컬렉션은 아이템 하나만 있거나 비어있더라도 배열로 표현합니다. <MUST>
A logical collection of resources MUST be represented as an array, even if it only contains one item or is empty.

[번역] JSON API Specification v1.0 (3) - Document Structure (2)

댓글