Data Model and Representations
727 | 728 |729 | See [[DID-CORE]] for normative requirements associated with the 730 | Data Model. 731 |
732 | 733 |734 | See [[DID-CORE]] for normative requirements associated with 735 | Representations. 736 |
737 | 738 |739 | There is no strong consensus regarding preserving data model properties 740 | across representations. 741 | Removing properties when converting a 742 | DID document can result in 743 | an inability to maintain 744 | interoperability with [[VC-DATA-MODEL]]. See Drawbacks and Benefits. 745 |
746 | 747 |Drawbacks
749 | 750 |751 | The DID document data model 752 | contains properties (such as `id`, 754 | `verificationMethod`, and `service`), which are 755 | defined in a way that is independent of a concrete representation. There 756 | are a number of known 757 | representations, 758 | including 759 | JSON 760 | and JSON-LD (defined by DID Core), and 762 | CBOR 764 | (defined by a DID WG Note). Additional representations 765 | (such as XML, YAML, CBOR-LD, and others) are possible and could be 766 | defined 767 | in the future. For each of these 768 | representations, a combination of production and consumption rules 769 | defines the concrete syntax of properties, 770 | but 771 | the semantics of properties are independent of any given representation. 772 | In other words, in every 773 | representation 774 | of a DID document, 775 | there is always a way to represent a `service` or a 776 | `verificationMethod`, and their meanings 777 | are consistent across conformant representations. 778 |
779 | 780 |781 | In addition to properties, a DID document may contain 783 | representation-specific 785 | entries which may be 786 | required by certain representations in order to fully represent the 787 | DID document data model and its 788 | properties. For example, the JSON-LD 789 | representation of a DID document 790 | (with media type 791 | `application/did+ld+json`) requires the 792 | `@context` representation-specific entry, in order to correctly express 793 | the semantics of properties such as 794 | `id`, 795 | `verificationMethod` or `service` within the JSON-LD representation. 796 | This enables JSON-LD’s semantics which are 797 | based on a decentralized, permissionless, open-world data model. 798 |
799 | 800 |801 | In contrast to this, the (non-LD) JSON 802 | representation (with media type `application/did+json`) does not 803 | have this semantic 804 | capability; instead, (non-LD) JSON documents always need agreement on 805 | semantics in some out-of-band way that is 806 | not part of the document itself. In the case of DID documents using the 807 | (non-LD) JSON representation, those 808 | semantics are 809 | typically established by the DID Spec 811 | Registries. 812 | Therefore, 813 | establishing semantics of DID document properties in the (non-LD) JSON 814 | representation does not require 815 | the representation-specific `@context` entry, as is required by the 816 | JSON-LD representation. 817 |
818 | 819 |820 | As with the (non-LD) JSON representation compared to the JSON-LD 821 | representation, similar considerations apply between the (non-LD) CBOR 822 | representation and the CBOR-LD representation. 823 |
824 | 825 |826 | Other examples of representation-specific 828 | entries could be XML 829 | namespace definitions or YAML tags, although 830 | these particular representations have not been defined at the time of 831 | this writing. 832 |
833 | 834 |835 | If an entry that is specific to one representation appears in another 836 | representation, it can be called a 837 | representation-foreign entry. An example of this is a 838 | `@context` 839 | entry appearing in the 840 | `application/did+json` 841 | representation. 842 |
843 | 844 |845 | Examples of representation-specific 847 | entries and 848 | representation-foreign entries: 849 |
850 | 851 |
855 | 862 | Avoid representation-foreign entries 863 |
864 | 865 |866 | It is bad practice and potentially harmful for producers to include 867 | "representation-foreign entries" in DID 868 | documents. 869 |
870 | 871 |872 | Different implementations of DID document consumers may or may not be 873 | able to properly understand the meaning 874 | and processing rules of representation-foreign entries. Since DIDs and 875 | DID documents form an open ecosystem 876 | with 877 | many producers and consumers, a producer cannot anticipate the 878 | behavior of a consumer with regard to 879 | representation-foreign entries. 880 |
881 | 882 |
883 | For example, if a producer adds an
884 | @context
885 | entry to a DID document in the
886 | application/did+json
887 | representation, some consumers (those that understand JSON-LD, such as
888 | JSON-LD document loaders) may process
889 | it
890 | in one way, while other consumers (those that only understand plain
891 | JSON, without any JSON-LD specific rules)
892 | may process it in a different way.
893 |
896 | This can lead to inconsistent behavior by consumers that cannot be 897 | predicted by a producer. 898 |
899 | 900 |904 | Reliance on representation-foreign entries 905 |
906 | 907 |908 | It is bad practice and potentially harmful for consumers to rely on 909 | representation-foreign entries in DID 910 | documents. 911 |
912 | 913 |914 | As a special case of the previous section, certain consumers may go as 915 | far as relying on the presence of 916 | representation-foreign entries. For example, an incorrectly 917 | implemented consumer of DID documents in the 918 | `application/did+json` representation may attempt to apply JSON-LD 919 | tooling to that representation. That 920 | tooling 921 | is dependent on the presence of the `@context` representation-foreign 922 | entry, which is not actually required 923 | (and 924 | in fact discouraged) to be used in the `application/did+json` 925 | representation. 926 |
927 | 928 |929 | The result is lack of interoperability, since such consumers will 930 | throw errors even if the returned DID 931 | document 932 | representation is actually conformant. 933 |
934 | 935 |939 | Security problems with representation-foreign entries 940 |
941 | 942 |943 | If some implementations of DID document consumers process 944 | representation-foreign entries, and others don’t, 945 | then 946 | this can lead to security holes, since the semantics of DID document 947 | properties will not be interpreted in a 948 | predictable way. 949 |
950 | 951 |952 | For example, consider the following DID document, and assume that the 953 | JSON-LD context 954 | `https://example.com/myextensions/other-definitions.jsonld` defines 955 | `blockchainAccountId` in a way that is different 956 | from the property 958 | listed in the DID 959 | Specification Registries. 960 |
961 | 962 |
964 | {
965 | "@context":[
966 | "https://www.w3.org/ns/did/v1",
967 | "https://example.com/myextensions/other-definitions.jsonld"
968 | ],
969 | "id":"did:example:123456789abcdefghi",
970 | "verificationMethod":[{
971 | "id": "did:example:123456789abcdefghi#vm-3",
972 | "controller": "did:example:123456789abcdefghi",
973 | "type": "EcdsaSecp256k1RecoveryMethod2020",
974 | "blockchainAccountId": "eip155:1:0xF3beAC30C498D9E26865F34fCAa57dBB935b0D74"
975 | }]
976 | }
977 |
978 |
979 | 980 | If this DID document is consumed as `application/did+json` by an 981 | implementation that doesn't understand 982 | JSON-LD, 983 | it will interpret `blockchainAccountId` as the property 985 | listed in the DID 986 | Specification Registries, and it will process it accordingly. 987 |
988 | 989 |990 | If the exact same DID document is consumed as `application/did+json` 991 | by an implementation that understands 992 | JSON-LD, it may interpret `blockchainAccountId` using the provided 993 | JSON-LD context, and therefore process it 994 | differently. 995 |
996 | 997 |998 | It is a common mistake to claim that "JSON-LD is just JSON", and to 999 | justify injecting the `@context` 1000 | representation-foreign entry into a DID document in the 1001 | `application/did+json` representation. This claim 1002 | however is true only on the syntax level, but wrong and dangerous on 1003 | the semantic level, especially when 1004 | security-related properties are involved. In the example above, 1005 | different consumer implementations are likely 1006 | to 1007 | come to different conclusions on how the DID can be controlled. 1008 |
1009 | 1010 |1011 | Representation-foreign entries in DID documents should be avoided, 1012 | since they can lead to inconsistent and 1013 | unpredictable DID control decisions. 1014 |
1015 | 1016 |1020 | Conversion between Representations 1021 |
1022 | 1023 |1024 | The DID document data model and the production/consumption rules of 1025 | representations have been designed to 1026 | enable 1027 | lossless conversion between representations. Conversion between 1028 | representations is achieved by executing the 1029 | consumption rules of the source representation, and then the 1030 | production rules of the target representation. 1031 |
1032 | 1033 |1034 | The DID Specification Registries [[DID-SPEC-REGISTRIES]] provide additional 1035 | information about properties as well as representation-specific 1036 | entries that help with such conversion. For 1037 | example, a DID document in the `application/did+json` representation 1038 | can be converted to the 1039 | `application/did+ld+json` representation by adding a `@context` 1040 | representation-specific entry during 1041 | production, 1042 | using the JSON-LD context information in the DID Specification Registries [[DID-SPEC-REGISTRIES]]. 1043 |
1044 | 1045 |1046 | Conversely, a DID document in the `application/did+ld+json` 1047 | representation can be converted to the 1048 | `application/did+json` representation by removing the `@context` 1049 | representation-specific entry during 1050 | consumption. 1051 |
1052 | 1053 |1054 | Representation-foreign entries in DID documents should be avoided, 1055 | since the implications on lossless 1056 | conversion 1057 | between representations is unclear. 1058 |
1059 | 1060 |Benefits
1066 | 1067 |
1068 | Implementers are not required to support all representations.
1069 | For example, an implementation might choose to only support
1070 | application/did+json,
1071 | and choose not to support application/did+ld+json,
1072 | application/did+dag+cbor,
1073 | application/did+xml, application/did+yaml,
1074 | etc...
1075 |
1078 | Implementers might prefer to use JSON or YAML representations to 1079 | implement both the 1080 | abstract data model and concrete reprepresentations. 1081 |
1082 | 1083 |1084 | When converting between an implementation of the abstract data model and 1085 | a 1086 | representation that is capable of preserving all properties, 1087 | all properties SHOULD be preserved. 1088 |
1089 | 1090 |For example, preserving @context in YAML,
1091 | allows for the document to later be used with
1092 | documentLoaders
1094 | that use
1095 | JSON-LD Framing
1096 | to perform
1097 | dereferencing.
1098 |
1102 | --- 1103 | "@context": 1104 | - https://www.w3.org/ns/did/v1 1105 | - https://w3id.org/security/suites/jws-2020/v1 1106 | id: did:key:z82Lkm8gN2PGD7WbUiTUKRHgSptPhGPAQG9HT9HybYE9LoKYwcikh5rAU9gGo3qTne3ZHf6 1107 | verificationMethod: 1108 | - id: did:key:z82Lkm8gN2PGD7WbUiTUKRHgSptPhGPAQG9HT9HybYE9LoKYwcikh5rAU9gGo3qTne3ZHf6#z82Lkm8gN2PGD7WbUiTUKRHgSptPhGPAQG9HT9HybYE9LoKYwcikh5rAU9gGo3qTne3ZHf6 1109 | type: JsonWebKey2020 1110 | controller: did:key:z82Lkm8gN2PGD7WbUiTUKRHgSptPhGPAQG9HT9HybYE9LoKYwcikh5rAU9gGo3qTne3ZHf6 1111 | publicKeyJwk: 1112 | kty: EC 1113 | crv: P-384 1114 | x: ELYfgFzSi43VGgKlyuYBKeoW00DmNqf5VuMWD1iUTTHQ8NRQrR4KHShzH_DrvOhh 1115 | y: sftqdHdso4JPQO3MLnsXmWbAFqjmHLgP8H_DZSLxx3ei9kLj_W3R6NhtH03bwE1C 1116 | assertionMethod: 1117 | - did:key:z82Lkm8gN2PGD7WbUiTUKRHgSptPhGPAQG9HT9HybYE9LoKYwcikh5rAU9gGo3qTne3ZHf6#z82Lkm8gN2PGD7WbUiTUKRHgSptPhGPAQG9HT9HybYE9LoKYwcikh5rAU9gGo3qTne3ZHf6 1118 | authentication: 1119 | - did:key:z82Lkm8gN2PGD7WbUiTUKRHgSptPhGPAQG9HT9HybYE9LoKYwcikh5rAU9gGo3qTne3ZHf6#z82Lkm8gN2PGD7WbUiTUKRHgSptPhGPAQG9HT9HybYE9LoKYwcikh5rAU9gGo3qTne3ZHf6 1120 | capabilityInvocation: 1121 | - did:key:z82Lkm8gN2PGD7WbUiTUKRHgSptPhGPAQG9HT9HybYE9LoKYwcikh5rAU9gGo3qTne3ZHf6#z82Lkm8gN2PGD7WbUiTUKRHgSptPhGPAQG9HT9HybYE9LoKYwcikh5rAU9gGo3qTne3ZHf6 1122 | capabilityDelegation: 1123 | - did:key:z82Lkm8gN2PGD7WbUiTUKRHgSptPhGPAQG9HT9HybYE9LoKYwcikh5rAU9gGo3qTne3ZHf6#z82Lkm8gN2PGD7WbUiTUKRHgSptPhGPAQG9HT9HybYE9LoKYwcikh5rAU9gGo3qTne3ZHf6 1124 | keyAgreement: 1125 | - did:key:z82Lkm8gN2PGD7WbUiTUKRHgSptPhGPAQG9HT9HybYE9LoKYwcikh5rAU9gGo3qTne3ZHf6#z82Lkm8gN2PGD7WbUiTUKRHgSptPhGPAQG9HT9HybYE9LoKYwcikh5rAU9gGo3qTne3ZHf6 1126 | 1127 |1128 | 1129 |
Preserving members across representations is also common 1130 | in 1131 | OpenAPI Specification 1132 | 3.1.0, 1133 | which supports 1134 | JSON 1136 | Schema 1137 | represented as YAML or JSON. 1138 |
1139 | 1140 |DID methods that support both application/did+ld+json and
1141 | application/did+json
1142 | ought to return application/did+json with an
1143 | @context, because it enables
1144 | both representations to be used with tooling and standards that support
1145 | semantics (such as [[VC-DATA-MODEL]]),
1146 | and because the default behavior of JSON processors is to ignore object
1147 | members that are not understood.
1148 |
DID document representations produced by an implementation ought to be 1151 | treated as immutable, 1152 | since any tampering, including adding, removing, or reordering core or 1153 | representation specific entries 1154 | might be considered malicious, since it alters the integrity of the 1155 | produced DID document.
1156 | 1157 |