Principle 1: Human-Readable Node Names

Statement

Use human-readable node names — for example, <publisher> instead of <spu> — to make the JSON structure intuitive for developers and non-technical stakeholders, and facilitate adoption.

Why

CWR EDI uses compact, coded record identifiers (e.g. SPU, OWR, SWR) for transmission efficiency. In JSON, these abbreviations reduce readability and slow adoption. Human-readable names improve onboarding, debugging, and documentation reuse without losing fidelity to the CWR 2.2 data model.

Visualization Example

{
  "work": {
    "title": "Example Work",
    "writers": [
      {
        "writer": {
          "ipiNameNumber": "123456789",
          "name": "Jane Smith"
        }
      }
    ],
    "publishers": [
      {
        "publisher": {
          "name": "Acme Publishing Ltd.",
          "publisherType": "E",
          "shareType": "own"
        }
      }
    ]
  }
}

Principle 2: Hierarchical JSON

Statement

Use JSON's native hierarchical structure instead of EDI's positional sequencing and record numbering.

Why

CWR EDI encodes relationships using transaction sequence numbers, record sequence numbers, and flat lists of differently prefixed records with fixed names. JSON eliminates these constraints and expresses relationships directly through nesting, improving clarity, validation and performance.

Visualization Example

{
  "work": {
    "iswc": "T1234567890",
    "tracks": [{
      "isrc": "US-ABC-23-00001",
      "releases": [{
        "title": "Release A1",
        "ean": "5099750442223"
      }]
    }]
  }
}

Principle 3: Contract Chains (OWN%) Start With Writers

Statement

OWN% Contract chains begin with Writers and continue through their representatives, such as Publishers and Sub-publishers. These chains express how contractual shares flow from Writers to the parties who act on their behalf.

Why

Writers are the origin of copyrights. Publishers derive their OWN% shares from Writers. Sub-Publishers collect for Original Publishers. JSON should reflect these relationships.

Visualization Example

own: {
  writers: [
    {
      role: "C",
      representedBy: [
        {
          role: "E",
          representedBy: [
            {
              role: "SE",
              ...
            }
          ]
        }
      ]
    }
  ]
}

Principle 4: No Groups (GRH/GRT)

Statement

GRH/GRT Group Header/Group Trailer constructs are not modeled.

Why

Groups are batching constructs defined for fixed-width EDI transmission. JSON payloads and files do not need them, and removing them simplifies structure and validation.

Visualization Example

none required

Principle 5: Parametric Design

Statement

Use attributes instead of creating additional node types, wherever possible. Represent meaning through parameters, avoid node name proliferation.

Why

JSON should avoid growth of node types (e.g. <submitterControlledPublisherRepresentedByASubpublisher>) by using parametric metadata, in order to contain complexity.

Visualization Example

// Bad:
"publisher": {
  "own": 100.00
}

// Better:
"publisher": {
  "shareType": "own",
  "sharePercent": 100.00
}

// Even better:
representedBy: [
  {
    "role": "E",
    "shareType": "own",
    "sharePercent": 100.00
    ...
  }
]

Principle 6: Works → Tracks → Releases

Statement

Represent the complete rights chain across Works → Tracks → Releases as 1:n relationships, to support multi-ISRC scenarios.

Why

CWR R3 allows multiple REC records per work. JSON must model this market reality:

• one Work can spawn multiple Tracks (Soundrecordings)
• one Track can appear on multiple Releases (Albums, Bundles, Digital Singles...)

Visualization Example

{
  "work": {
    "title": "Example Work",
    "iswc": "T1234567890",
    "tracks": [{
      "title": "Example Track A",
      "isrc": "US-AAA-23-00001",
      "releases": [{
        "title": "Release A1",
        "ean": "5099750442223"
      }, {
        "title": "Release A2",
        "ean": "8808678223451"
      }]
    }, {
      "title": "Example Track B",
      "isrc": "US-AAA-23-00002",
      "releases": [{
        "title": "Release B1",
        "ean": "6025178824451"
      }]
    }]
  }
}

Principle 7: French Role Abbreviations

Statement

Use CISAC's French role abbreviations: C Compositeur, A Auteur, AR Arrangeur, E Éditeur, SE Sous-Éditeur...etc. Allow optional Role Names in English.

Why

Maintains continuity with EDI and industry practice while supporting optional multilingual clarity.

Visualization Example

{
  "role": "C",
  "roleName": "Composer"
}

Principle 8: Territory Codes (TIS + ISO)

Statement

Use CISAC Territory Codes adapted from ISO-3166 with include/exclude structures.

Why

Territory logic in CWR is change-prone and high-impact (e.g. "European Union", code: 2123) but an established industry standard. Until all actors can migrate to a simplified Territory+ISO Country Code (e.g. "WORLD excluding DE+AT+CH") approach, this is necessary to maintain compatibility.

Visualization Example

"territories": {
  "include": [2136],
  "exclude": [276, 40, 756]
}

Principle 9: Messages vs. Flags

Statement

Distinguish between Messages (requests or transaction-level state) and Flags (descriptive metadata).

Why

EDI mixes types: e.g., Revocation Indicator ("revoke this work" = do-something) vs. AI Indicator ("this work uses AI").

Examples:
Messages: Revocation, Relinquishment, Change Requests, Register Work (NWR).
Flags: AI Usage, Fraudulent flag.

Visualization Example

{
  "messages": {
    "revocation": {
      "indicator": "Y",
      "reason": "03"
    }
  },
  "flags": {
    "aiUsage": "M",
    "fraudulent": false,
    "anomalous": false
  }
}

Principle 10: OWN and COLL

Statement

OWN% models derivative contractual shares along the writer–publisher chain. COLL% models how much each Interested Party collects per rightsType and territory.

Why

OWN% preserve the original contractual share picture for society registrations and Publisher-to-Publisher exchanges. COLL% provide a separate territorial collection view and can represent any collecting entity, including those without writer-derived shares such as Income Participants.

Visualization Example

own: {
  writers: [
    {
      role: "C",
      shares: [
        { rightsType: "pr", value: 42.67, society: "035" },
        { rightsType: "mr", value: 30.00, society: "035" }
      ],
      representedBy: [
        {
          role: "E",
          shares: [
            { rightsType: "pr", value: 21.33, society: "035" },
            { rightsType: "mr", value: 20.00, society: "035" }
          ]...
        }
      ]
    },
    {
      role: "A",
      shares: [
        { rightsType: "pr", value: 24.00, society: "035" },
        { rightsType: "mr", value: 30.00, society: "035" }
      ],
      representedBy: [
        {
          role: "E",
          shares: [
            { rightsType: "pr", value: 12.00, society: "035" },
            { rightsType: "mr", value: 20.00, society: "035" }
          ]
        }
      ]
    }
  ]
}

Principle 11: Territory COLL%

Statement

COLL% express territorial collection shares. They specify which participants collect which Rights Types in which territories, without relying on writer-derived splits.

Why

Writers, publishers, subpublishers, Bénéficiaires du Paiement and other collecting entities are assigned per territory and per society. Societies issue different agreement numbers per territory and representative. Keeping these elements in the territorial layer of COLL% prevents mixing derived shares with collection shares.

Visualization Example

coll: [
  {
    territories: {
      include: ["276", "040", "756"],
      exclude: [],
      participants: [
        {
          role: "C",
          shares: [
            { rightsType: "pr", value: 25.00, society: "035" },
            { rightsType: "mr", value: 0.00, society: "035" }
          ]
        },
        {
          role: "A",
          shares: [
            { rightsType: "pr", value: 25.00, society: "035" },
            { rightsType: "mr", value: 0.00, society: "035" }
          ]
        },
        {
          role: "SE",
          shares: [
            { rightsType: "pr", value: 50.00, society: "035" },
            { rightsType: "mr", value: 100.00, society: "035" }
          ]
          ...
        }
      ]
    }
  }
]

Principle 12: Domestic and International Work Titles

Statement

Support Domestic, International, and Alternate Work Titles in UTF-8. In CWR EDI, the international title sits in the NWR/REV record, while non-Roman and alternate titles use NAT, NET, and ALT records with Title Type codes.

Why

CWR treats every title as a variant identified by its Title Type. A unified JSON structure preserves this behaviour, supports all scripts without ASCII limits, and allows domestic, international, and alternate titles to coexist.

Visualization Example

{
  "workTitles": [
    { "value": "夜に駆ける", "type": "OL", "language": "ja" },
    { "value": "Racing into the Night", "type": "TT" },
    { "value": "Yoru ni Kakeru", "type": "ALT" }
  ]
}