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.