update readme; add release notes; update version; update ienumerables…

… to ireadonlylists

Graeae.Models.Tests/PayloadValidationTests.cs

@@ -27,7 +27,7 @@ public async Task ReferencesValid(string fileName)
 		var document = JsonDocument.Parse(payloadJson);
 
 		var results = openApiDoc.EvaluatePayload(document, componentRef, options);
-		Assert.True(results.IsValid);
+		Assert.True(results!.IsValid);
 	}
 
 
@@ -55,6 +55,6 @@ public async Task ReferencesInvalid(string fileName)
 		var document = JsonDocument.Parse(payloadJson);
 
 		var results = openApiDoc.EvaluatePayload(document, componentRef, options);
-		Assert.False(results.IsValid);
+		Assert.False(results!.IsValid);
 	}
 }

Graeae.Models/Graeae.Models.csproj

@@ -16,11 +16,11 @@
     <PackageIcon>openapi.png</PackageIcon>
     <RepositoryUrl>https://github.com/gregsdennis/Graeae</RepositoryUrl>
     <PackageTags>openapi json schema models</PackageTags>
-    <PackageReleaseNotes>Release notes can be found at https://github.com/gregsdennis/Graeae</PackageReleaseNotes>
+    <PackageReleaseNotes>Edit Release notes in file RELEASE_NOTES.md in the repo root.</PackageReleaseNotes>
     <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
     <DocumentationFile>Graeae.Models.xml</DocumentationFile>
-    <Version>0.3.0</Version>
-    <FileVersion>0.3.0.0</FileVersion>
+    <Version>0.3.1</Version>
+    <FileVersion>0.3.1.0</FileVersion>
     <AssemblyVersion>0.3.0.0</AssemblyVersion>
     <IncludeSymbols>true</IncludeSymbols>
     <SymbolPackageFormat>snupkg</SymbolPackageFormat>
@@ -53,4 +53,12 @@
     <PackageReference Include="Yaml2JsonNode" Version="2.1.0" />
   </ItemGroup>
 
+  <Target Name="PreparePackageReleaseNotesFromFile" BeforeTargets="GenerateNuspec">
+    <ReadLinesFromFile File="../RELEASE-NOTES.md" >
+      <Output TaskParameter="Lines" ItemName="ReleaseNoteLines"/>
+    </ReadLinesFromFile>
+    <PropertyGroup>
+      <PackageReleaseNotes>@(ReleaseNoteLines, '%0a')</PackageReleaseNotes>
+    </PropertyGroup>
+  </Target>
 </Project>

Graeae.Models/OpenApiDocument.cs

@@ -52,7 +52,7 @@ public class OpenApiDocument : IBaseDocument
 	/// <summary>
 	/// Gets or sets the server collection.
 	/// </summary>
-	public IEnumerable<Server>? Servers { get; set; }
+	public IReadOnlyList<Server>? Servers { get; set; }
 	/// <summary>
 	/// Gets or sets the paths collection.
 	/// </summary>
@@ -68,11 +68,11 @@ public class OpenApiDocument : IBaseDocument
 	/// <summary>
 	/// Gets or sets the security requirements collection.
 	/// </summary>
-	public IEnumerable<SecurityRequirement>? Security { get; set; }
+	public IReadOnlyList<SecurityRequirement>? Security { get; set; }
 	/// <summary>
 	/// Gets or sets the tags.
 	/// </summary>
-	public IEnumerable<Tag>? Tags { get; set; }
+	public IReadOnlyList<Tag>? Tags { get; set; }
 	/// <summary>
 	/// Gets or sets external documentation.
 	/// </summary>

Graeae.Models/OpenApiExtensions.cs

@@ -16,9 +16,9 @@ public static class OpenApiExtensions
 	/// <param name="openApiDocument">The OpenAPI document.</param>
 	/// <param name="payload">The payload to validate.</param>
 	/// <param name="schemaLocation">The location within the document where the schema can be found.</param>
-	/// <param name="options">The evaluation options.  This should be the same options object used to initialize the OpenAPI document.</param>
+	/// <param name="options">(optional) The evaluation options.  This should be the same options object used to initialize the OpenAPI document.</param>
 	/// <returns>The evaluation options if the schema was found; otherwise null.</returns>
-	public static EvaluationResults? EvaluatePayload(this OpenApiDocument openApiDocument, JsonNode? payload, JsonPointer schemaLocation, EvaluationOptions options)
+	public static EvaluationResults? EvaluatePayload(this OpenApiDocument openApiDocument, JsonNode? payload, JsonPointer schemaLocation, EvaluationOptions? options = null)
 	{
 		var schema = openApiDocument.Find<JsonSchema>(schemaLocation);
 
@@ -31,9 +31,9 @@ public static class OpenApiExtensions
 	/// <param name="openApiDocument">The OpenAPI document.</param>
 	/// <param name="payload">The payload to validate.</param>
 	/// <param name="schemaLocation">The location within the document where the schema can be found.</param>
-	/// <param name="options">The evaluation options.  This should be the same options object used to initialize the OpenAPI document.</param>
+	/// <param name="options">(optional) The evaluation options.  This should be the same options object used to initialize the OpenAPI document.</param>
 	/// <returns>The evaluation options if the schema was found; otherwise null.</returns>
-	public static EvaluationResults? EvaluatePayload(this OpenApiDocument openApiDocument, JsonDocument payload, JsonPointer schemaLocation, EvaluationOptions options)
+	public static EvaluationResults? EvaluatePayload(this OpenApiDocument openApiDocument, JsonDocument payload, JsonPointer schemaLocation, EvaluationOptions? options = null)
 	{
 		var schema = openApiDocument.Find<JsonSchema>(schemaLocation);
 
@@ -46,9 +46,9 @@ public static class OpenApiExtensions
 	/// <param name="openApiDocument">The OpenAPI document.</param>
 	/// <param name="payload">The payload to validate.</param>
 	/// <param name="schemaLocation">The location within the document where the schema can be found.</param>
-	/// <param name="options">The evaluation options.  This should be the same options object used to initialize the OpenAPI document.</param>
+	/// <param name="options">(optional) The evaluation options.  This should be the same options object used to initialize the OpenAPI document.</param>
 	/// <returns>The evaluation options if the schema was found; otherwise null.</returns>
-	public static EvaluationResults? EvaluatePayload(this OpenApiDocument openApiDocument, JsonElement payload, JsonPointer schemaLocation, EvaluationOptions options)
+	public static EvaluationResults? EvaluatePayload(this OpenApiDocument openApiDocument, JsonElement payload, JsonPointer schemaLocation, EvaluationOptions? options = null)
 	{
 		var schema = openApiDocument.Find<JsonSchema>(schemaLocation);
 

Graeae.Models/Operation.cs

@@ -30,7 +30,7 @@ public class Operation : IRefTargetContainer
 	/// <summary>
 	/// Gets or sets the tags.
 	/// </summary>
-	public IEnumerable<string>? Tags { get; set; }
+	public IReadOnlyList<string>? Tags { get; set; }
 	/// <summary>
 	/// Gets or sets the summary.
 	/// </summary>
@@ -50,7 +50,7 @@ public class Operation : IRefTargetContainer
 	/// <summary>
 	/// Gets or sets the parameters.
 	/// </summary>
-	public IEnumerable<Parameter>? Parameters { get; set; }
+	public IReadOnlyList<Parameter>? Parameters { get; set; }
 	/// <summary>
 	/// Gets or sets the request body.
 	/// </summary>
@@ -70,11 +70,11 @@ public class Operation : IRefTargetContainer
 	/// <summary>
 	/// Gets or sets the security requirements.
 	/// </summary>
-	public IEnumerable<SecurityRequirement>? Security { get; set; }
+	public IReadOnlyList<SecurityRequirement>? Security { get; set; }
 	/// <summary>
 	/// Gets or sets the server collection.
 	/// </summary>
-	public IEnumerable<Server>? Servers { get; set; }
+	public IReadOnlyList<Server>? Servers { get; set; }
 	/// <summary>
 	/// Gets or set extension data.
 	/// </summary>

Graeae.Models/PathItem.cs

@@ -70,11 +70,11 @@ public class PathItem : IRefTargetContainer
 	/// <summary>
 	/// Gets or sets the collection of servers.
 	/// </summary>
-	public IEnumerable<Server>? Servers { get; set; }
+	public IReadOnlyList<Server>? Servers { get; set; }
 	/// <summary>
 	/// Gets or sets the collection of parameters.
 	/// </summary>
-	public IEnumerable<Parameter>? Parameters { get; set; }
+	public IReadOnlyList<Parameter>? Parameters { get; set; }
 	/// <summary>
 	/// Gets or set extension data.
 	/// </summary>

Graeae.Models/SerializationExtensions.cs

@@ -28,7 +28,7 @@ public static T Expect<T>(this JsonObject obj, string propertyName, string objec
 		return factory(value);
 	}
 
-	public static IEnumerable<T>? MaybeArray<T>(this JsonObject obj, string propertyName, Func<JsonNode?, T> factory)
+	public static IReadOnlyList<T>? MaybeArray<T>(this JsonObject obj, string propertyName, Func<JsonNode?, T> factory)
 	{
 		if (!obj.TryGetPropertyValue(propertyName, out var array)) return null;
 		if (array is not JsonArray map)

Graeae.Models/ServerVariable.cs

@@ -20,7 +20,7 @@ public class ServerVariable : IRefTargetContainer
 	/// <summary>
 	/// Gets or sets an enumeration of string values to be used if the substitution options are from a limited set.
 	/// </summary>
-	public IEnumerable<string>? Enum { get; set; }
+	public IReadOnlyList<string>? Enum { get; set; }
 	/// <summary>
 	/// Gets the default value to use for substitution.
 	/// </summary>

README.md

@@ -43,6 +43,29 @@ var asText = YamlSerializer.Serialize(openApiDoc);
 
 During initialization, if the document contains references that cannot be resolved, a `RefResolutionException` will be thrown.
 
+### Payload Validation
+
+To validate a payload against a JSON Schema within your OpenAPI document, use the `.EvaluatePayload()` extension method.
+
+```c#
+var payload = JsonNode.Parse("<content from HttpRequest or elsewhere>");
+var schemaComponentLocation = JsonPointer.Parse("/pointer/to/schema");
+var results = openApiDoc.EvaluatePayload(payload, schemaComponentLocation);
+```
+
+If your schema is under the `paths` section in the OpenAPI document, it may be easier and more readable to get the pointer using the `JsonPointer.Create()` method and passing the individual segments.  This avoids having to escape forward slashes `/`.
+
+```c#
+var schemaInPathLocation = JsonPointer.Create("paths", "/pets/{petId}", "get", "parameters", 0 , "schema");
+```
+
+Of course, if the path is well-known at dev time, you can also just access it directly:
+
+```c#
+var schemaInPath = openApiDoc.Paths["/pets/{petId}"].Get.Parameters[0].Schema;
+var results = schemaInPath.Evaluate(payload);
+```
+
 ### OpenAPI 3.0.x and JSON Schema Draft 4
 
 To support OpenAPI v3.0.x, you'll need to enable JSON Schema draft 4 support first.  To do that, add this to your app initialization:

RELEASE_NOTES.md

@@ -0,0 +1,13 @@
+[0.3.1](https://github.com/gregsdennis/Graeae/pull/10)
+
+- Added `.EvaluatePayload()` extension on `OpenApiDocument`.
+- Updated array members from `IEnumerable<T>` to `IReadOnlyList<T>` to enable indexer access.
+
+[0.3.0](https://github.com/gregsdennis/Graeae/pull/6)
+
+- Updated _JsonSchema.Net_.
+- Set up for Native AOT.
+
+[0.2.1](https://github.com/gregsdennis/Graeae/pull/4)
+
+Automatically register draft 4 `type` keyword.