|
791 | 791 | </section>
|
792 | 792 |
|
793 | 793 | <section title='Schema References With "$ref"'>
|
794 |
| - <t> |
795 |
| - The "$ref" keyword is used to reference a schema, and provides the ability to |
796 |
| - validate recursive structures through self-reference. |
797 |
| - </t> |
798 |
| - <t> |
799 |
| - An object schema with a "$ref" property MUST be interpreted as a "$ref" reference. |
800 |
| - The value of the "$ref" property MUST be a URI Reference. |
801 |
| - Resolved against the current URI base, it identifies the URI of a schema to use. |
802 |
| - All other properties in a "$ref" object MUST be ignored. |
803 |
| - </t> |
804 |
| - <t> |
805 |
| - The URI is not a network locator, only an identifier. A schema need not be |
806 |
| - downloadable from the address if it is a network-addressable URL, and |
807 |
| - implementations SHOULD NOT assume they should perform a network operation when they |
808 |
| - encounter a network-addressable URI. |
809 |
| - </t> |
810 |
| - <t> |
811 |
| - A schema MUST NOT be run into an infinite loop against a schema. For example, if two |
812 |
| - schemas "#alice" and "#bob" both have an "allOf" property that refers to the other, |
813 |
| - a naive validator might get stuck in an infinite recursive loop trying to validate |
814 |
| - the instance. |
815 |
| - Schemas SHOULD NOT make use of infinite recursive nesting like this; the behavior is |
816 |
| - undefined. |
817 |
| - </t> |
| 794 | + <section title='Direct References with "$ref"'> |
| 795 | + <t> |
| 796 | + The "$ref" keyword is used to reference a schema, and provides the ability |
| 797 | + to validate recursive structures through self-reference. |
| 798 | + </t> |
| 799 | + <t> |
| 800 | + An object schema with a "$ref" property MUST be interpreted as a "$ref" |
| 801 | + reference. The value of the "$ref" property MUST be a URI Reference. |
| 802 | + Resolved against the current URI base, it identifies the URI of a schema |
| 803 | + to use. All other properties in a "$ref" object MUST be ignored. |
| 804 | + </t> |
| 805 | + <t> |
| 806 | + The URI is not a network locator, only an identifier. A schema need not be |
| 807 | + downloadable from the address if it is a network-addressable URL, and |
| 808 | + implementations SHOULD NOT assume they should perform a network operation |
| 809 | + when they encounter a network-addressable URI. |
| 810 | + </t> |
| 811 | + <t> |
| 812 | + A schema MUST NOT be run into an infinite loop against a schema. For |
| 813 | + example, if two schemas "#alice" and "#bob" both have an "allOf" property |
| 814 | + that refers to the other, a naive validator might get stuck in an infinite |
| 815 | + recursive loop trying to validate the instance. Schemas SHOULD NOT make |
| 816 | + use of infinite recursive nesting like this; the behavior is undefined. |
| 817 | + </t> |
| 818 | + </section> |
| 819 | + |
| 820 | + <section title='Recursive references with "$recurse"'> |
| 821 | + <t> |
| 822 | + This keyword's value MUST be the boolean literal true. |
| 823 | + <cref> |
| 824 | + Future drafts may extend the usage with other values. The immediate |
| 825 | + use case does not require any targets other than the entry point |
| 826 | + root, and a regular fragment URI reference does not provide the |
| 827 | + correct semantics. Should other values be added in the future, |
| 828 | + it is expected that a boolean true value will remain an alias for |
| 829 | + this original use case. |
| 830 | + </cref> |
| 831 | + </t> |
| 832 | + <t> |
| 833 | + The presence of this keyword with a boolean true value indicates that, |
| 834 | + during processing, it MUST be treated as a reference to the |
| 835 | + <xref target="schema-documents">schema document</xref> where processing |
| 836 | + was initiated. |
| 837 | + </t> |
| 838 | + <t> |
| 839 | + This document, known as the entry point schema, is the schema document that |
| 840 | + was initially supplied to the implementation, as opposed to schema documents |
| 841 | + that were processed as a result of following a "$ref" reference. Note that |
| 842 | + even if processing began at a subschema within a document, the "$recurse" |
| 843 | + target MUST be the root of the document. |
| 844 | + </t> |
| 845 | + <t> |
| 846 | + Aside from the dynamic definition of the reference target, a "$recurse" |
| 847 | + reference MUST behave identically to a "$ref" reference. |
| 848 | + </t> |
| 849 | + <figure> |
| 850 | + <preamble> |
| 851 | + Given the following schemas: |
| 852 | + </preamble> |
| 853 | + <artwork> |
| 854 | +<![CDATA[ |
| 855 | +{ |
| 856 | + "$schema": "http://json-schema.org/draft-08/schema#", |
| 857 | + "$id": "https://example.com/base", |
| 858 | + "properties": { |
| 859 | + "local": { |
| 860 | + "$ref": "#", |
| 861 | + }, |
| 862 | + "recursive": { |
| 863 | + "$recurse": true |
| 864 | + } |
| 865 | + } |
| 866 | +} |
| 867 | +
|
| 868 | +{ |
| 869 | + "$schema": "http://json-schema.org/draft-08/schema#", |
| 870 | + "$id": "https://example.com/extension", |
| 871 | + "properties": { |
| 872 | + "extended": { |
| 873 | + "$ref": "https://example.com/base", |
| 874 | + } |
| 875 | + } |
| 876 | +} |
| 877 | +]]> |
| 878 | + </artwork> |
| 879 | + </figure> |
| 880 | + <t> |
| 881 | + When an implementation begins processing with the |
| 882 | + "https://example.com/base" schema, both the "local" and "recursive" |
| 883 | + references resolve to "https://example.com/base". The entry point |
| 884 | + schema and the schema being processed are the same. |
| 885 | + </t> |
| 886 | + <t> |
| 887 | + However, when an implementation begins processing with the |
| 888 | + "https://example.com/extension" schema, and processes the |
| 889 | + "https://example.com/base" schema as a result of following the "$ref" |
| 890 | + within the "extended" property, now the entry point schema is |
| 891 | + "https://example.com/extension". |
| 892 | + </t> |
| 893 | + <t> |
| 894 | + Therefore the "local" property's reference |
| 895 | + still resolves to "https://example.com/base" while the "recursive" |
| 896 | + property's reference now resolves to "https://example.com/extension". |
| 897 | + This behavior remains the same even if the implementation begins processing |
| 898 | + at "https://example.com/extension#/properties/extended". |
| 899 | + </t> |
| 900 | + </section> |
| 901 | + |
818 | 902 | <section title="Loading a referenced schema">
|
819 | 903 | <t>
|
820 |
| - The use of URIs to identify remote schemas does not necessarily mean anything is downloaded, |
821 |
| - but instead JSON Schema implementations SHOULD understand ahead of time which schemas they will be using, |
822 |
| - and the URIs that identify them. |
| 904 | + The use of URIs to identify remote schemas does not necessarily mean |
| 905 | + anything is downloaded, but instead JSON Schema implementations SHOULD |
| 906 | + understand ahead of time which schemas they will be using, and the URIs |
| 907 | + that identify them. |
823 | 908 | </t>
|
824 | 909 | <t>
|
825 |
| - When schemas are downloaded, |
826 |
| - for example by a generic user-agent that doesn't know until runtime which schemas to download, |
827 |
| - see <xref target="hypermedia">Usage for Hypermedia</xref>. |
| 910 | + When schemas are downloaded, for example by a generic user-agent that |
| 911 | + doesn't know until runtime which schemas to download, see |
| 912 | + <xref target="hypermedia">Usage for Hypermedia</xref>. |
828 | 913 | </t>
|
829 | 914 | <t>
|
830 | 915 | Implementations SHOULD be able to associate arbitrary URIs with an arbitrary
|
|
850 | 935 | </t>
|
851 | 936 | <t>
|
852 | 937 | If the resulting URI identifies a schema within the current document, or
|
853 |
| - within another schema document that has been made available to the implementation, |
854 |
| - then that schema SHOULD be used automatically. |
| 938 | + within another schema document that has been made available to the |
| 939 | + implementation, then that schema SHOULD be used automatically. |
855 | 940 | </t>
|
856 | 941 | <t>
|
857 | 942 | For example, consider this schema:
|
|
905 | 990 | </section>
|
906 | 991 | </section>
|
907 | 992 |
|
908 |
| - <section title='Recursive references with "$recurse"'> |
909 |
| - <t> |
910 |
| - This keyword's value MUST be the boolean literal true. |
911 |
| - <cref> |
912 |
| - Future drafts may extend the usage with other values. The immediate |
913 |
| - use case does not require any targets other than the entry point |
914 |
| - root, and a regular fragment URI reference does not provide the |
915 |
| - correct semantics. Should other values be added in the future, |
916 |
| - it is expected that a boolean true value will remain an alias for |
917 |
| - this original use case. |
918 |
| - </cref> |
919 |
| - </t> |
920 |
| - <t> |
921 |
| - The presence of this keyword with a boolean true value indicates that, |
922 |
| - during processing, it MUST be treated as a reference to the |
923 |
| - <xref target="schema-documents">schema document</xref> where processing |
924 |
| - was initiated. |
925 |
| - </t> |
926 |
| - <t> |
927 |
| - This document, known as the entry point schema, is the schema document that |
928 |
| - was initially supplied to the implementation, as opposed to schema documents |
929 |
| - that were processed as a result of following a "$ref" reference. Note that |
930 |
| - even if processing began at a subschema within a document, the "$recurse" |
931 |
| - target MUST be the root of the document. |
932 |
| - </t> |
933 |
| - <t> |
934 |
| - Aside from the dynamic definition of the reference target, a "$recurse" |
935 |
| - reference MUST behave identically to a "$ref" reference. |
936 |
| - </t> |
937 |
| - <figure> |
938 |
| - <preamble> |
939 |
| - Given the following schemas: |
940 |
| - </preamble> |
941 |
| - <artwork> |
942 |
| -<![CDATA[ |
943 |
| -{ |
944 |
| - "$schema": "http://json-schema.org/draft-08/schema#", |
945 |
| - "$id": "https://example.com/base", |
946 |
| - "properties": { |
947 |
| - "local": { |
948 |
| - "$ref": "#", |
949 |
| - }, |
950 |
| - "recursive": { |
951 |
| - "$recurse": true |
952 |
| - } |
953 |
| - } |
954 |
| -} |
955 |
| -
|
956 |
| -{ |
957 |
| - "$schema": "http://json-schema.org/draft-08/schema#", |
958 |
| - "$id": "https://example.com/extension", |
959 |
| - "properties": { |
960 |
| - "extended": { |
961 |
| - "$ref": "https://example.com/base", |
962 |
| - } |
963 |
| - } |
964 |
| -} |
965 |
| -]]> |
966 |
| - </artwork> |
967 |
| - </figure> |
968 |
| - <t> |
969 |
| - When an implementation begins processing with the |
970 |
| - "https://example.com/base" schema, both the "local" and "recursive" |
971 |
| - references resolve to "https://example.com/base". The entry point |
972 |
| - schema and the schema being processed are the same. |
973 |
| - </t> |
974 |
| - <t> |
975 |
| - However, when an implementation begins processing with the |
976 |
| - "https://example.com/extension" schema, and processes the |
977 |
| - "https://example.com/base" schema as a result of following the "$ref" |
978 |
| - within the "extended" property, now the entry point schema is |
979 |
| - "https://example.com/extension". |
980 |
| - </t> |
981 |
| - <t> |
982 |
| - Therefore the "local" property's reference |
983 |
| - still resolves to "https://example.com/base" while the "recursive" property's |
984 |
| - reference now resolves to "https://example.com/extension". |
985 |
| - This behavior remains the same even if the implementation begins processing |
986 |
| - at "https://example.com/extension#/properties/extended". |
987 |
| - </t> |
988 |
| - </section> |
989 |
| - |
990 | 993 | <section title='Schema Re-Use With "$defs"'>
|
991 | 994 | <t>
|
992 | 995 | The "$defs" keyword provides a standardized location for schema
|
|
0 commit comments