From 568af23089d3266c9bbf14d5ad8ab165daa96745 Mon Sep 17 00:00:00 2001
From: Paul Mach <paul@mach.org>
Date: Wed, 31 Jan 2024 19:52:57 -0800
Subject: [PATCH] rerun docs.sh and add ref_test.sh to github workflow

---
 .github/docs/openapi3.txt | 48 +++++++++++++++++++++++++++++++++++++++
 .github/workflows/go.yml  |  3 +++
 2 files changed, 51 insertions(+)

diff --git a/.github/docs/openapi3.txt b/.github/docs/openapi3.txt
index 8b146f02c..ccf2f69d3 100644
--- a/.github/docs/openapi3.txt
+++ b/.github/docs/openapi3.txt
@@ -180,6 +180,10 @@ func (callback *Callback) Value(key string) *PathItem
     Value returns the callback for key or nil
 
 type CallbackRef struct {
+	// Extensions only captures fields starting with 'x-' as no other fields
+	// are allowed by the openapi spec.
+	Extensions map[string]interface{}
+
 	Ref   string
 	Value *Callback
 	// Has unexported fields.
@@ -353,6 +357,10 @@ func (example *Example) Validate(ctx context.Context, opts ...ValidationOption)
     Validate returns an error if Example does not comply with the OpenAPI spec.
 
 type ExampleRef struct {
+	// Extensions only captures fields starting with 'x-' as no other fields
+	// are allowed by the openapi spec.
+	Extensions map[string]interface{}
+
 	Ref   string
 	Value *Example
 	// Has unexported fields.
@@ -437,6 +445,10 @@ func (header *Header) Validate(ctx context.Context, opts ...ValidationOption) er
     Validate returns an error if Header does not comply with the OpenAPI spec.
 
 type HeaderRef struct {
+	// Extensions only captures fields starting with 'x-' as no other fields
+	// are allowed by the openapi spec.
+	Extensions map[string]interface{}
+
 	Ref   string
 	Value *Header
 	// Has unexported fields.
@@ -530,6 +542,10 @@ func (link *Link) Validate(ctx context.Context, opts ...ValidationOption) error
     Validate returns an error if Link does not comply with the OpenAPI spec.
 
 type LinkRef struct {
+	// Extensions only captures fields starting with 'x-' as no other fields
+	// are allowed by the openapi spec.
+	Extensions map[string]interface{}
+
 	Ref   string
 	Value *Link
 	// Has unexported fields.
@@ -823,6 +839,10 @@ func (parameter *Parameter) WithRequired(value bool) *Parameter
 func (parameter *Parameter) WithSchema(value *Schema) *Parameter
 
 type ParameterRef struct {
+	// Extensions only captures fields starting with 'x-' as no other fields
+	// are allowed by the openapi spec.
+	Extensions map[string]interface{}
+
 	Ref   string
 	Value *Parameter
 	// Has unexported fields.
@@ -1047,6 +1067,10 @@ func (requestBody *RequestBody) WithSchema(value *Schema, consumes []string) *Re
 func (requestBody *RequestBody) WithSchemaRef(value *SchemaRef, consumes []string) *RequestBody
 
 type RequestBodyRef struct {
+	// Extensions only captures fields starting with 'x-' as no other fields
+	// are allowed by the openapi spec.
+	Extensions map[string]interface{}
+
 	Ref   string
 	Value *RequestBody
 	// Has unexported fields.
@@ -1108,6 +1132,10 @@ func (m ResponseBodies) JSONLookup(token string) (interface{}, error)
     https://pkg.go.dev/github.com/go-openapi/jsonpointer#JSONPointable
 
 type ResponseRef struct {
+	// Extensions only captures fields starting with 'x-' as no other fields
+	// are allowed by the openapi spec.
+	Extensions map[string]interface{}
+
 	Ref   string
 	Value *Response
 	// Has unexported fields.
@@ -1395,6 +1423,10 @@ func (err *SchemaError) JSONPointer() []string
 func (err SchemaError) Unwrap() error
 
 type SchemaRef struct {
+	// Extensions only captures fields starting with 'x-' as no other fields
+	// are allowed by the openapi spec.
+	Extensions map[string]interface{}
+
 	Ref   string
 	Value *Schema
 	// Has unexported fields.
@@ -1541,6 +1573,10 @@ func (ss *SecurityScheme) WithScheme(value string) *SecurityScheme
 func (ss *SecurityScheme) WithType(value string) *SecurityScheme
 
 type SecuritySchemeRef struct {
+	// Extensions only captures fields starting with 'x-' as no other fields
+	// are allowed by the openapi spec.
+	Extensions map[string]interface{}
+
 	Ref   string
 	Value *SecurityScheme
 	// Has unexported fields.
@@ -1722,6 +1758,12 @@ type ValidationOption func(options *ValidationOptions)
     ValidationOption allows the modification of how the OpenAPI document is
     validated.
 
+func AllowExtensionsWithRef() ValidationOption
+    AllowExtensionsWithRef allows extensions (fields starting with 'x-') as
+    siblings for $ref fields. This is the default. Non-extension fields are
+    prohibited unless allowed explicitly with the AllowExtraSiblingFields
+    option.
+
 func AllowExtraSiblingFields(fields ...string) ValidationOption
     AllowExtraSiblingFields called as AllowExtraSiblingFields("description")
     makes Validate not return an error when said field appears next to a $ref.
@@ -1762,6 +1804,12 @@ func EnableSchemaPatternValidation() ValidationOption
     DisableSchemaPatternValidation. By default, schema pattern validation is
     enabled.
 
+func ProhibitExtensionsWithRef() ValidationOption
+    ProhibitExtensionsWithRef causes the validation to return an error if
+    extensions (fields starting with 'x-') are found as siblings for $ref
+    fields. Non-extension fields are prohibited unless allowed explicitly with
+    the AllowExtraSiblingFields option.
+
 type ValidationOptions struct {
 	// Has unexported fields.
 }
diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml
index acb3a0f0d..2604468b0 100644
--- a/.github/workflows/go.yml
+++ b/.github/workflows/go.yml
@@ -55,6 +55,9 @@ jobs:
     - run: ./refs.sh | tee openapi3/refs.go
     - run: git --no-pager diff --exit-code
 
+    - run: ./refs_test.sh | tee openapi3/refs_test.go
+    - run: git --no-pager diff --exit-code
+
     - run: ./maps.sh
     - run: git --no-pager diff --exit-code