support $self keyword coming in v3.2

karenetheridge · karenetheridge · commit d3027c0688cc · 2025-04-11T13:56:36.000-07:00
see OAI/OpenAPI-Specification#4389
diff --git a/Changes b/Changes
@@ -3,6 +3,8 @@ Revision history for OpenAPI-Modern
 {{$NEXT}}
           - no longer require the user to define a custom metaschema when
             changing jsonSchemaDialect (we dynamically create one for you)
+          - pre-emptive support for '$self' property in the OpenAPI document
+            (to be officially added in v3.2)
 
 0.083     2025-02-28 23:48:29Z
           - fix Sereal serialization and deserialization hooks
diff --git a/lib/JSON/Schema/Modern/Document/OpenAPI.pm b/lib/JSON/Schema/Modern/Document/OpenAPI.pm
@@ -51,6 +51,10 @@ has '+evaluator' => (
   required => 1,
 );
 
+has '+schema' => (
+  isa => HashRef,
+);
+
 has '+metaschema_uri' => (
   lazy => 1,
   default => DEFAULT_BASE_METASCHEMA,
@@ -113,6 +117,11 @@ sub traverse ($self, $evaluator, $config_override = {}) {
     type => 'object',
     required => ['openapi'],
     properties => {
+      '$self' => {
+        type => 'string',
+        format => 'uri-reference',
+        pattern => '',  # just here for the callback so we can customize the error
+      },
       openapi => {
         type => 'string',
         pattern => '',  # just here for the callback so we can customize the error
@@ -131,7 +140,11 @@ sub traverse ($self, $evaluator, $config_override = {}) {
       validate_formats => 1,
       callbacks => {
         pattern => sub ($data, $schema, $state) {
-          return $data =~ /^3\.1\.[0-9]+(-.+)?$/ ? 1 : E($state, 'unrecognized openapi version %s', $data);
+          return E($state, 'unrecognized openapi version %s', $data)
+            if $state->{data_path} eq '/openapi' and $data !~ /^3\.1\.[0-9]+(-.+)?$/;
+          return E($state, '$self cannot contain a fragment')
+            if $state->{data_path} eq '/$self' and $data =~ /#/;
+          return 1;
         },
       },
     },
@@ -141,8 +154,9 @@ sub traverse ($self, $evaluator, $config_override = {}) {
     return $state;
   }
 
-  # in v3.2, we will use the resolved form of the uri in '$self'
-  $self->_set_canonical_uri($state->{initial_schema_uri} = $self->original_uri);
+  # determine canonical uri using rules from §?? (v3.2) "Establishing the Base URI"
+  $self->_set_canonical_uri($state->{initial_schema_uri} =
+    Mojo::URL->new($schema->{'$self'}//())->to_abs($self->retrieval_uri));
 
   # /jsonSchemaDialect: https://spec.openapis.org/oas/v3.1#specifying-schema-dialects
   {
@@ -172,6 +186,14 @@ sub traverse ($self, $evaluator, $config_override = {}) {
       if not $self->_has_metaschema_uri and $json_schema_dialect ne DEFAULT_DIALECT;
   }
 
+  $state->{identifiers}{$state->{initial_schema_uri}} = {
+    path => '',
+    canonical_uri => $state->{initial_schema_uri},
+    specification_version => $state->{spec_version},
+    vocabularies => $state->{vocabularies}, # reference, not copy
+    configs => {},
+  };
+
   # evaluate the document against its metaschema to find any errors, to identify all schema
   # resources within to add to the global resource index, and to extract all operationIds
   my (@json_schema_paths, @operation_paths, %bad_path_item_refs, @servers_paths);
@@ -370,6 +392,14 @@ sub _add_vocab_and_default_schemas ($self) {
       $js->add_document($base.'/latest', $document);
     }
   }
+
+  # dirty hack! patch in support for $self, until v3.2
+  $js->{_resource_index}{'https://spec.openapis.org/oas/3.1/schema/2024-11-14'}{document}->schema->{properties}{'$self'} = {
+    type => 'string',
+    format => 'uri-reference',
+    '$comment' => 'MUST NOT be empty, and MUST NOT contain a fragment',
+    pattern => '^[^#]+$',
+  } if exists $self->schema->{'$self'};
 }
 
 # https://spec.openapis.org/oas/v3.1#schema-object
@@ -407,14 +437,15 @@ sub _traverse_schema ($self, $state) {
     }
 
     foreach my $anchor (sort keys $new->{anchors}->%*) {
-      if (my $existing_anchor = $existing->{anchors}{$anchor}) {
+      if (my $existing_anchor = ($existing->{anchors}//{})->{$anchor}) {
         ()= E({ %$state, schema_path => $new->{anchors}{$anchor}{path} },
           'duplicate anchor uri "%s" found (original at path "%s")',
           $new->{canonical_uri}->clone->fragment($anchor),
           $existing->{anchors}{$anchor}{path});
         next;
       }
 
+      use autovivification 'store';
       $existing->{anchors}{$anchor} = $new->{anchors}{$anchor};
     }
   }
diff --git a/t/document-toplevel.t b/t/document-toplevel.t
@@ -42,36 +42,23 @@ subtest 'basic construction' => sub {
   );
 };
 
-subtest 'top level document fields' => sub {
-  my $doc = JSON::Schema::Modern::Document::OpenAPI->new(
-    canonical_uri => 'http://localhost:1234/api',
-    evaluator => my $js = JSON::Schema::Modern->new,
-    schema => 1,
-  );
-
-  cmp_result(
-    [ map $_->TO_JSON, $doc->errors ],
-    [
-      {
-        instanceLocation => '',
-        keywordLocation => '/type',
-        absoluteKeywordLocation => DEFAULT_METASCHEMA.'#/type',
-        error => 'got integer, not object',
-      },
-    ],
+subtest 'top level document checks' => sub {
+  die_result(
+    sub {
+      JSON::Schema::Modern::Document::OpenAPI->new(
+        canonical_uri => 'http://localhost:1234/api',
+        evaluator => JSON::Schema::Modern->new,
+        schema => 1,
+      );
+    },
+    qr/^Value "1" did not pass type constraint "HashRef"/,
     'document is wrong type',
   );
 
-  is(
-    document_result($doc),
-    q!'': got integer, not object!,
-    'stringified errors',
-  );
 
-
-  $doc = JSON::Schema::Modern::Document::OpenAPI->new(
+  my $doc = JSON::Schema::Modern::Document::OpenAPI->new(
     canonical_uri => 'http://localhost:1234/api',
-    evaluator => $js = JSON::Schema::Modern->new,
+    evaluator => my $js = JSON::Schema::Modern->new,
     schema => {},
   );
   cmp_result(
@@ -190,6 +177,45 @@ ERRORS
 ERRORS
 
 
+  $doc = JSON::Schema::Modern::Document::OpenAPI->new(
+    canonical_uri => 'http://localhost:1234/api',
+    evaluator => $js,
+    schema => {
+      openapi => OAS_VERSION,
+      info => {
+        title => 'my title',
+        version => '1.2.3',
+      },
+      '$self' => '#frag\\ment',
+    },
+  );
+
+  cmp_result(
+    [ map $_->TO_JSON, $doc->errors ],
+    [
+      {
+        instanceLocation => '/$self',
+        keywordLocation => '/properties/$self/pattern',
+        absoluteKeywordLocation => DEFAULT_METASCHEMA.'#/properties/$self/pattern',
+        error => '$self cannot contain a fragment',
+      },
+      {
+        instanceLocation => '/$self',
+        keywordLocation => '/properties/$self/format',
+        absoluteKeywordLocation => DEFAULT_METASCHEMA.'#/properties/$self/format',
+        error => 'not a valid uri-reference string',
+      },
+      {
+        instanceLocation => '',
+        keywordLocation => '/properties',
+        absoluteKeywordLocation => DEFAULT_METASCHEMA.'#/properties',
+        error => 'not all properties are valid',
+      },
+    ],
+    'invalid $self uri, with custom error message',
+  );
+
+
   $doc = JSON::Schema::Modern::Document::OpenAPI->new(
     canonical_uri => 'http://localhost:1234/api',
     evaluator => $js,
@@ -463,6 +489,138 @@ ERRORS
     }),
     'dialect resources are properly stored on the evaluator',
   );
+
+
+  # relative $self, absolute original_uri - $self is resolved with original_uri
+  $doc = JSON::Schema::Modern::Document::OpenAPI->new(
+    canonical_uri => 'http://localhost:1234/foo/api.json',
+    evaluator => $js,
+    schema => {
+      openapi => OAS_VERSION,
+      info => {
+        title => 'my title',
+        version => '1.2.3',
+      },
+      '$self' => 'user/api.json',  # the 'user' family of APIs
+      paths => {},
+    },
+  );
+
+  is($doc->original_uri, 'http://localhost:1234/foo/api.json', 'retrieval uri');
+  is($doc->canonical_uri, 'http://localhost:1234/foo/user/api.json', 'canonical uri is $self resolved against retrieval uri');
+  cmp_deeply(
+    $doc->{resource_index},
+    {
+      'http://localhost:1234/foo/user/api.json' => {
+        canonical_uri => str('http://localhost:1234/foo/user/api.json'),
+        path => '',
+        specification_version => 'draft2020-12',
+        vocabularies => bag(map 'JSON::Schema::Modern::Vocabulary::'.$_,
+          qw(Core Applicator Validation FormatAnnotation Content MetaData Unevaluated OpenAPI)),
+        configs => {},
+      },
+    },
+    'resource is properly indexed',
+  );
+
+
+  # absolute $self, absolute original_uri - $self is used as is
+  $doc = JSON::Schema::Modern::Document::OpenAPI->new(
+    canonical_uri => 'http://localhost:1234/foo/api.json',
+    evaluator => $js,
+    schema => {
+      openapi => OAS_VERSION,
+      info => {
+        title => 'my title',
+        version => '1.2.3',
+      },
+      '$self' => 'http://localhost:5555/user/api.json',  # the 'user' family of APIs
+      paths => {},
+    },
+  );
+
+  is($doc->original_uri, 'http://localhost:1234/foo/api.json', 'retrieval uri');
+  is($doc->canonical_uri, 'http://localhost:5555/user/api.json', 'canonical uri is $self, already absolute');
+  cmp_deeply(
+    $doc->{resource_index},
+    {
+      'http://localhost:5555/user/api.json' => {
+        canonical_uri => str('http://localhost:5555/user/api.json'),
+        path => '',
+        specification_version => 'draft2020-12',
+        vocabularies => bag(map 'JSON::Schema::Modern::Vocabulary::'.$_,
+          qw(Core Applicator Validation FormatAnnotation Content MetaData Unevaluated OpenAPI)),
+        configs => {},
+      },
+    },
+    'resource is properly indexed',
+  );
+
+
+  # relative $self, relative original_uri - $self is resolved with original_uri
+  $doc = JSON::Schema::Modern::Document::OpenAPI->new(
+    canonical_uri => 'foo/api.json',
+    evaluator => $js,
+    schema => {
+      openapi => OAS_VERSION,
+      info => {
+        title => 'my title',
+        version => '1.2.3',
+      },
+      '$self' => 'user/api.json',  # the 'user' family of APIs
+      paths => {},
+    },
+  );
+
+  is($doc->original_uri, 'foo/api.json', 'retrieval uri');
+  is($doc->canonical_uri, 'foo/user/api.json', 'canonical uri is $self resolved against retrieval uri');
+  cmp_deeply(
+    $doc->{resource_index},
+    {
+      'foo/user/api.json' => {
+        canonical_uri => str('foo/user/api.json'),
+        path => '',
+        specification_version => 'draft2020-12',
+        vocabularies => bag(map 'JSON::Schema::Modern::Vocabulary::'.$_,
+          qw(Core Applicator Validation FormatAnnotation Content MetaData Unevaluated OpenAPI)),
+        configs => {},
+      },
+    },
+    'resource is properly indexed',
+  );
+
+
+  # absolute $self, relative original_uri - $self is used as is
+  $doc = JSON::Schema::Modern::Document::OpenAPI->new(
+    canonical_uri => 'foo/api.json',
+    evaluator => $js,
+    schema => {
+      openapi => OAS_VERSION,
+      info => {
+        title => 'my title',
+        version => '1.2.3',
+      },
+      '$self' => 'http://localhost:5555/user/api.json',  # the 'user' family of APIs
+      paths => {},
+    },
+  );
+
+  is($doc->original_uri, 'foo/api.json', 'retrieval uri');
+  is($doc->canonical_uri, 'http://localhost:5555/user/api.json', 'canonical uri is $self, already absolute');
+  cmp_deeply(
+    $doc->{resource_index},
+    {
+      'http://localhost:5555/user/api.json' => {
+        canonical_uri => str('http://localhost:5555/user/api.json'),
+        path => '',
+        specification_version => 'draft2020-12',
+        vocabularies => bag(map 'JSON::Schema::Modern::Vocabulary::'.$_,
+          qw(Core Applicator Validation FormatAnnotation Content MetaData Unevaluated OpenAPI)),
+        configs => {},
+      },
+    },
+    'resource is properly indexed',
+  );
 };
 
 done_testing;
diff --git a/t/openapi-constructor.t b/t/openapi-constructor.t
@@ -85,38 +85,11 @@ subtest 'missing arguments' => sub {
 };
 
 subtest 'document errors' => sub {
-  my $result;
-  try {
-    OpenAPI::Modern->new(
-      openapi_uri => '/api',
-      openapi_schema => [ 'this is not a valid openapi document' ],
-    )
-  }
-  catch ($e) {
-    $result = $e;
-  }
-
-  cmp_result(
-    $result->TO_JSON,
-    {
-      valid => false,
-      errors => [
-        {
-          instanceLocation => '',
-          keywordLocation => '/type',
-          absoluteKeywordLocation => DEFAULT_METASCHEMA.'#/type',
-          error => 'got array, not object',
-        },
-      ],
-    },
+  die_result(
+    sub { OpenAPI::Modern->new(openapi_uri => '/api', openapi_schema => [ 'invalid openapi document' ]) },
+    qr/^Reference \["invalid openapi document"\] did not pass type constraint "HashRef"/,
     'bad document causes validation to immediately fail',
   );
-
-  is(
-    "$result",
-    q!'': got array, not object!,
-    'exception during construction serializes the error correctly',
-  );
 };
 
 subtest 'construct with document' => sub {
