extract, doc definitions_non_fundamental

README.md

@@ -39,15 +39,10 @@ tables in an RDBMS with suitable columns and types.
 
 To try to make the data model represent the "real" data, it applies heuristics:
 
-- to remove object definitions that only have one property (which the
-author calls "thin objects"), or that have two properties, one of whose
-names has the substring "count" (case-insensitive).
+- to remove object definitions considered non-fundamental; see
+["definitions\_non\_fundamental"](#definitions_non_fundamental).
 - for definitions that have `allOf`, either merge them together if there
 is a `discriminator`, or absorb properties from referred definitions
-- to find object definitions that have all the same properties as another,
-and remove all but the shortest-named one
-- to remove object definitions whose properties are a strict subset
-of another
 - creates object definitions for any properties that are an object
 - creates object definitions for any properties that are an array of simple
 OpenAPI types (e.g. `string`)
@@ -102,6 +97,26 @@ in the definitions. Not exported. E.g.
       d2 => (1 << 1) | (1 << 2),
     }
 
+## definitions\_non\_fundamental
+
+Given the `definitions` of an OpenAPI spec, will return a hash-ref
+mapping names of definitions considered non-fundamental to a
+value. The value is either the name of another definition that _is_
+fundamental, or or `undef` if it just contains e.g. a string. It will
+instead be a reference to such a value if it is to an array of such.
+
+This may be used e.g. to determine the "real" input or output of an
+OpenAPI operation.
+
+Non-fundamental is determined according to these heuristics:
+
+- object definitions that only have one property (which the author calls
+"thin objects"), or that have two properties, one of whose names has
+the substring "count" (case-insensitive).
+- object definitions that have all the same properties as another, and
+are not the shortest-named one between the two.
+- object definitions whose properties are a strict subset of another.
+
 # OPENAPI SPEC EXTENSIONS
 
 ## `x-id-field`

lib/SQL/Translator/Parser/OpenAPI.pm

@@ -604,6 +604,16 @@ sub _map_thru {
   \%mapped;
 }
 
+sub definitions_non_fundamental {
+  my ($defs) = @_;
+  my $thin2real = _strip_thin($defs);
+  my $def2mask = defs2mask($defs);
+  my $reffed = _find_referenced($defs, $thin2real);
+  my $dup2real = _strip_dup($defs, $def2mask, $reffed);
+  my $subset2real = _strip_subset($defs, $def2mask, $reffed);
+  _map_thru({ %$thin2real, %$dup2real, %$subset2real });
+}
+
 sub parse {
   my ($tr, $data) = @_;
   my $openapi_schema = JSON::Validator::OpenAPI->new->schema($data)->schema;
@@ -614,12 +624,7 @@ sub parse {
   _remove_fields(\%defs, 'x-artifact');
   _remove_fields(\%defs, 'x-input-only');
   %defs = %{ _merge_allOf(\%defs) };
-  my $thin2real = _strip_thin(\%defs);
-  my $def2mask = defs2mask(\%defs);
-  my $reffed = _find_referenced(\%defs, $thin2real);
-  my $dup2real = _strip_dup(\%defs, $def2mask, $reffed);
-  my $subset2real = _strip_subset(\%defs, $def2mask, $reffed);
-  my $bestmap = _map_thru({ %$thin2real, %$dup2real, %$subset2real });
+  my $bestmap = definitions_non_fundamental(\%defs);
   delete @defs{keys %$bestmap};
   %defs = %{ _extract_objects(\%defs) };
   %defs = %{ _extract_array_simple(\%defs) };
@@ -689,9 +694,8 @@ To try to make the data model represent the "real" data, it applies heuristics:
 
 =item *
 
-to remove object definitions that only have one property (which the
-author calls "thin objects"), or that have two properties, one of whose
-names has the substring "count" (case-insensitive).
+to remove object definitions considered non-fundamental; see
+L</definitions_non_fundamental>.
 
 =item *
 
@@ -700,16 +704,6 @@ is a C<discriminator>, or absorb properties from referred definitions
 
 =item *
 
-to find object definitions that have all the same properties as another,
-and remove all but the shortest-named one
-
-=item *
-
-to remove object definitions whose properties are a strict subset
-of another
-
-=item *
-
 creates object definitions for any properties that are an object
 
 =item *
@@ -778,6 +772,38 @@ in the definitions. Not exported. E.g.
     d2 => (1 << 1) | (1 << 2),
   }
 
+=head2 definitions_non_fundamental
+
+Given the C<definitions> of an OpenAPI spec, will return a hash-ref
+mapping names of definitions considered non-fundamental to a
+value. The value is either the name of another definition that I<is>
+fundamental, or or C<undef> if it just contains e.g. a string. It will
+instead be a reference to such a value if it is to an array of such.
+
+This may be used e.g. to determine the "real" input or output of an
+OpenAPI operation.
+
+Non-fundamental is determined according to these heuristics:
+
+=over
+
+=item *
+
+object definitions that only have one property (which the author calls
+"thin objects"), or that have two properties, one of whose names has
+the substring "count" (case-insensitive).
+
+=item *
+
+object definitions that have all the same properties as another, and
+are not the shortest-named one between the two.
+
+=item *
+
+object definitions whose properties are a strict subset of another.
+
+=back
+
 =head1 OPENAPI SPEC EXTENSIONS
 
 =head2 C<x-id-field>