diff --git a/.github/workflows/meta-ci.yml b/.github/workflows/meta-ci.yml new file mode 100644 index 0000000..89bd02a --- /dev/null +++ b/.github/workflows/meta-ci.yml @@ -0,0 +1,25 @@ +name: Test EventsModel.Meta + +on: + push: + branches: [dev, master] + pull_request: + +permissions: + contents: read + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-dotnet@v4 + with: + dotnet-version: | + 8.0.x + 9.0.x + 10.0.x + - name: Test all supported frameworks + run: dotnet test tests/EventsModel.Meta.Tests/EventsModel.Meta.Tests.csproj -c Release -p:GeneratePackageOnBuild=false + - name: Verify package + run: dotnet pack src/EventsModel.Meta/EventsModel.Meta.csproj -c Release --no-build -p:GeneratePackageOnBuild=false -o artifacts diff --git a/.gitignore b/.gitignore index 01da99d..c38e244 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,6 @@ .vs/ .vscode/ +**/bin/ +**/obj/ +**/TestResults/ +/artifacts/ diff --git a/EventsModel.slnx b/EventsModel.slnx index 2e0df69..4a8327a 100644 --- a/EventsModel.slnx +++ b/EventsModel.slnx @@ -1,4 +1,6 @@ + + diff --git a/README.md b/README.md index f4fb363..9ac3779 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,11 @@ Install-Package Skyware.Lis.EventsModel Read the documentaion and see the object model on [this site](https://skyware-group.github.io/EventsModel/articles/getting-started.html). +For documented JSON schemas, message discovery and JSON parsing, see +[EventsModel.Meta](src/EventsModel.Meta/README.md). + +Typical connection URL is like `activemq:failover:ssl://some-host.com:61616?transport.acceptInvalidBrokerCert=true`. Also you will need username and password to acces the ActiveMQ server. + ## End to end example You could use example code in [TestApp](TestApp/Program.cs) for fast project bootstrap. This application uses [Apache.NMS](https://activemq.apache.org/components/nms/) client library diff --git a/src/.gitignore b/src/.gitignore index d849780..7763953 100644 --- a/src/.gitignore +++ b/src/.gitignore @@ -75,6 +75,7 @@ StyleCopReport.xml *_h.h *.ilk *.meta +!EventsModel.Meta/ *.obj *.iobj *.pch diff --git a/src/EventsModel.Meta/EventsModel.Meta.csproj b/src/EventsModel.Meta/EventsModel.Meta.csproj new file mode 100644 index 0000000..27fe478 --- /dev/null +++ b/src/EventsModel.Meta/EventsModel.Meta.csproj @@ -0,0 +1,40 @@ + + + + net8.0;net9.0;net10.0 + enable + enable + Skyware.Lis.EventsModel.Meta + Skyware.Lis.EventsModel.Meta + Skyware.Lis.EventsModel.Meta + 0.9.1 + Documented JSON schemas, message discovery and parsing for LIS iLab events. + Mikhail Kalatchev + SKYWARE Group + MIT + https://github.com/SKYWARE-Group/EventsModel + README.md + true + + + + + + + + + + + + + + + + + + + + diff --git a/src/EventsModel.Meta/MessageCatalog.cs b/src/EventsModel.Meta/MessageCatalog.cs new file mode 100644 index 0000000..9a4da51 --- /dev/null +++ b/src/EventsModel.Meta/MessageCatalog.cs @@ -0,0 +1,290 @@ +using System.Collections.Concurrent; +using System.Reflection; +using System.Text; +using System.Text.Json; +using System.Text.Json.Nodes; +using System.Text.Json.Schema; +using System.Text.Json.Serialization; +using System.Text.Json.Serialization.Metadata; +using Json.Schema; + +namespace Skyware.Lis.EventsModel.Meta; + +/// +/// Discovers messages, exports documented JSON schemas and recognizes/parses incoming JSON. +/// +/// +/// Uses the compiled model's serialization contract and embedded XML documentation. No MCP host is required. +/// +public sealed class MessageCatalog +{ + private const string ModelNamespace = "Skyware.Lis.EventsModel."; + private readonly ModelDocumentation documentation = new(); + private readonly JsonSerializerOptions serializer; + private readonly Type[] messageTypes; + private readonly Dictionary discriminators; + private readonly string? discriminatorProperty; + private readonly int maxBytes; + private readonly int maxDepth; + private readonly ConcurrentDictionary schemas = new(); + + /// + /// Creates a reusable catalog; options are copied and cannot subsequently alter the catalog. + /// + public MessageCatalog(MessageCatalogOptions? options = null) + { + options ??= new(); + if (options.MaxMessageBytes <= 0 || options.MaxDepth <= 0) + throw new ArgumentOutOfRangeException(nameof(options), "Input limits must be positive."); + maxBytes = options.MaxMessageBytes; + maxDepth = options.MaxDepth; + discriminatorProperty = options.DiscriminatorPropertyName; + if (discriminatorProperty is not null && string.IsNullOrWhiteSpace(discriminatorProperty)) + throw new ArgumentException("Discriminator property must not be empty.", nameof(options)); + if (discriminatorProperty is null && options.DiscriminatorMappings.Count > 0) + throw new ArgumentException("Discriminator mappings require a property name.", nameof(options)); + serializer = new JsonSerializerOptions + { + PropertyNamingPolicy = options.PropertyNamingPolicy, + TypeInfoResolver = new DefaultJsonTypeInfoResolver(), + UnmappedMemberHandling = JsonUnmappedMemberHandling.Disallow, + MaxDepth = maxDepth + }; + serializer.MakeReadOnly(); + messageTypes = typeof(BaseMessage).Assembly.GetExportedTypes() + .Where(t => !t.IsAbstract && typeof(BaseMessage).IsAssignableFrom(t)) + .OrderBy(TypeId, StringComparer.Ordinal).ToArray(); + discriminators = options.DiscriminatorMappings.ToDictionary(x => x.Key, x => ResolveMessageType(x.Value), StringComparer.Ordinal); + if (discriminatorProperty is not null && messageTypes.Any(t => + serializer.GetTypeInfo(t).Properties.Any(p => p.Name == discriminatorProperty))) + throw new ArgumentException("Discriminator conflicts with a model property.", nameof(options)); + } + + /// + /// Returns every concrete BaseMessage subtype, sorted by its namespace-qualified model ID. + /// + public IReadOnlyList ListMessageTypes() => messageTypes.Select(DescribeType).ToArray(); + + /// + /// Returns a standalone schema, descriptions and a synthetic example for a message type. + /// + /// + /// Relative model ID, full CLR name, or unambiguous simple name. + /// + public MessageDescription DescribeMessage(string type) => Describe(ResolveMessageType(type)); + + /// + /// Exports a standalone JSON Schema 2020-12 document for any public model object or enum. + /// + public JsonObject GetSchema() => GetSchema(typeof(T)); + + /// + /// Exports a standalone schema. Only types from the model assembly are accepted. + /// + public JsonObject GetSchema(Type type) + { + ArgumentNullException.ThrowIfNull(type); + if (type.Assembly != typeof(BaseMessage).Assembly || !type.IsPublic || (!type.IsClass && !type.IsEnum)) + throw new ArgumentException("Type must be a public model class or enum.", nameof(type)); + return (JsonObject)GetEntry(type).Schema.DeepClone(); + } + + /// + /// Validates JSON and returns every compatible type with documentation; never ranks or guesses. + /// + public MessageExplanation ExplainMessage(string json) => Explain(json, null); + + /// + /// Deserializes only when exactly one type is identified, or validates an explicitly supplied type. + /// + /// + /// Invalid, unknown or ambiguous message. + /// + public BaseMessage ParseMessage(string json, string? type = null) + { + var explanation = Explain(json, type is null ? null : ResolveMessageType(type)); + if (explanation.Status != MessageMatchStatus.Matched) throw new MessageParseException(explanation); + var selected = ResolveMessageType(explanation.Candidates[0].MessageType.Type); + return Deserialize(explanation.Message!.Value, selected); + } + + private MessageExplanation Explain(string json, Type? requestedType) + { + ArgumentNullException.ThrowIfNull(json); + JsonElement message; + try + { + if (Encoding.UTF8.GetByteCount(json) > maxBytes) throw new JsonException("Message exceeds the configured UTF-8 size limit."); + using var document = JsonDocument.Parse(json, new JsonDocumentOptions { MaxDepth = maxDepth }); + RejectDuplicateProperties(document.RootElement); + message = document.RootElement.Clone(); + } + catch (JsonException e) + { + return new(MessageMatchStatus.InvalidJson, null, [], [new(null, e.Path ?? "", e.Message)]); + } + if (message.ValueKind != JsonValueKind.Object) + return new(MessageMatchStatus.InvalidMessage, message, [], [new(null, "", "A message must be a JSON object.")]); + + Type[] selected = requestedType is null ? messageTypes : [requestedType]; + var explicitType = requestedType is not null; + if (discriminatorProperty is not null && message.TryGetProperty(discriminatorProperty, out var discriminator)) + { + if (discriminator.ValueKind != JsonValueKind.String || !discriminators.TryGetValue(discriminator.GetString()!, out var resolved)) + return new(MessageMatchStatus.UnknownDiscriminator, message, [], + [new(null, "/" + Escape(discriminatorProperty), "Discriminator must be a registered string value.")]); + if (requestedType is not null && requestedType != resolved) + return new(MessageMatchStatus.InvalidMessage, message, [], + [new(TypeId(requestedType), "/" + Escape(discriminatorProperty), "Discriminator conflicts with the requested type.")]); + selected = [resolved]; + explicitType = true; + } + + var matches = new List(); + var errors = new List(); + foreach (var candidate in selected) + { + var result = GetEntry(candidate).Validator.Evaluate(message, new EvaluationOptions + { + OutputFormat = OutputFormat.List, + // JSON Schema's format is an annotation by default. The serializer below validates + // dates using the actual .NET wire contract, including DateTime without an offset. + RequireFormatValidation = false + }); + if (!result.IsValid) + { + CollectErrors(result, TypeId(candidate), errors); + continue; + } + try + { + // The serializer additionally checks CLR constraints, e.g. Int32 overflow. + Deserialize(message, candidate); + matches.Add(Describe(candidate)); + } + catch (JsonException e) { errors.Add(new(TypeId(candidate), e.Path ?? "", e.Message)); } + } + var status = matches.Count switch + { + 0 => explicitType ? MessageMatchStatus.InvalidMessage : MessageMatchStatus.NoMatch, + 1 => MessageMatchStatus.Matched, + _ => MessageMatchStatus.Ambiguous + }; + return new(status, message, matches.ToArray(), matches.Count == 0 ? errors.ToArray() : []); + } + + private BaseMessage Deserialize(JsonElement message, Type type) + { + if (discriminatorProperty is not null && message.TryGetProperty(discriminatorProperty, out _)) + { + var payload = JsonNode.Parse(message.GetRawText())!.AsObject(); + payload.Remove(discriminatorProperty); + return (BaseMessage)payload.Deserialize(type, serializer)!; + } + return (BaseMessage)message.Deserialize(type, serializer)!; + } + + private SchemaEntry GetEntry(Type type) => schemas.GetOrAdd(type, BuildSchema); + + private SchemaEntry BuildSchema(Type type) + { + var schema = serializer.GetJsonSchemaAsNode(type, new JsonSchemaExporterOptions + { + TransformSchemaNode = (context, node) => + { + if (node is not JsonObject obj) return node; + var member = context.PropertyInfo?.AttributeProvider as MemberInfo ?? context.TypeInfo.Type; + var description = documentation.Describe(member); + if (description.Length > 0) obj["description"] = description; + if (context.PropertyInfo?.Get is not null && context.PropertyInfo.Set is null) obj["readOnly"] = true; + var enumType = Nullable.GetUnderlyingType(context.TypeInfo.Type) ?? context.TypeInfo.Type; + if (enumType.IsEnum) + { + var values = new JsonArray(); + foreach (var field in enumType.GetFields(BindingFlags.Public | BindingFlags.Static)) + values.Add(new JsonObject + { + ["name"] = field.Name, + ["value"] = JsonSerializer.SerializeToNode(field.GetValue(null), enumType, serializer), + ["description"] = documentation.Describe(field) + }); + obj["x-enumDescriptions"] = values; + } + return obj; + } + }).AsObject(); + schema["$schema"] = "https://json-schema.org/draft/2020-12/schema"; + schema["title"] = TypeId(type); + if (typeof(BaseMessage).IsAssignableFrom(type) && !type.IsAbstract) + { + schema["type"] = "object"; // Messages themselves cannot be null; nested nullability is preserved. + if (discriminatorProperty is not null) + { + var values = discriminators.Where(x => x.Value == type).Select(x => x.Key).Order(StringComparer.Ordinal).ToArray(); + if (values.Length > 0) + schema["properties"]!.AsObject()[discriminatorProperty] = new JsonObject + { + ["type"] = "string", + ["enum"] = new JsonArray(values.Select(x => (JsonNode?)JsonValue.Create(x)).ToArray()), + ["description"] = "Explicit message type discriminator configured by the consumer." + }; + } + } + var validator = JsonSchema.FromText(schema.ToJsonString(), new BuildOptions + { + Dialect = Dialect.Draft202012, + SchemaRegistry = new() + }); + return new(schema, validator); + } + + private MessageDescription Describe(Type type) + { + var schema = GetSchema(type); + var example = SchemaExample.Create(schema); + return new(DescribeType(type), schema, + [new("Synthetic structural example generated from the schema; values are illustrative, not clinical guidance.", example)]); + } + + private MessageTypeInfo DescribeType(Type type) => new(TypeId(type), type.FullName!, documentation.Describe(type), + ((BaseMessage)Activator.CreateInstance(type)!).DefaultAddress); + + private Type ResolveMessageType(string name) + { + ArgumentException.ThrowIfNullOrWhiteSpace(name); + var matches = messageTypes.Where(t => TypeId(t) == name || t.FullName == name || t.Name == name).ToArray(); + return matches.Length switch + { + 1 => matches[0], + 0 => throw new ArgumentException($"Unknown message type '{name}'. Use ListMessageTypes().", nameof(name)), + _ => throw new ArgumentException($"Ambiguous type name '{name}'. Use a namespace-qualified model ID.", nameof(name)) + }; + } + + private static string TypeId(Type type) => type.FullName![ModelNamespace.Length..]; + private static string Escape(string value) => value.Replace("~", "~0").Replace("/", "~1"); + + private static void RejectDuplicateProperties(JsonElement element) + { + if (element.ValueKind == JsonValueKind.Object) + { + var names = new HashSet(StringComparer.Ordinal); + foreach (var property in element.EnumerateObject()) + { + if (!names.Add(property.Name)) throw new JsonException($"Duplicate JSON property '{property.Name}'."); + RejectDuplicateProperties(property.Value); + } + } + else if (element.ValueKind == JsonValueKind.Array) + foreach (var item in element.EnumerateArray()) RejectDuplicateProperties(item); + } + + private static void CollectErrors(EvaluationResults result, string type, List errors) + { + if (result.IsValid) return; + if (result.Errors is not null) + foreach (var error in result.Errors.Values) errors.Add(new(type, result.InstanceLocation.ToString(), error)); + if (result.Details is not null) + foreach (var child in result.Details) CollectErrors(child, type, errors); + } +} diff --git a/src/EventsModel.Meta/MessageCatalogOptions.cs b/src/EventsModel.Meta/MessageCatalogOptions.cs new file mode 100644 index 0000000..2a53386 --- /dev/null +++ b/src/EventsModel.Meta/MessageCatalogOptions.cs @@ -0,0 +1,34 @@ +using System.Text.Json; + +namespace Skyware.Lis.EventsModel.Meta; + +/// +/// Options for the wire format understood by a catalog. Defaults match System.Text.Json. +/// +public sealed class MessageCatalogOptions +{ + /// + /// Property naming policy; null preserves the model's PascalCase property names. + /// + public JsonNamingPolicy? PropertyNamingPolicy { get; init; } + + /// + /// Optional top-level string discriminator, e.g. "$type". No discriminator is assumed by default. + /// + public string? DiscriminatorPropertyName { get; init; } + + /// + /// Maps discriminator values to catalog type IDs. Values are never resolved through Type.GetType. + /// + public IReadOnlyDictionary DiscriminatorMappings { get; init; } = new Dictionary(); + + /// + /// Maximum UTF-8 input size. Defaults to one MiB. + /// + public int MaxMessageBytes { get; init; } = 1024 * 1024; + + /// + /// Maximum input nesting depth. Defaults to 64. + /// + public int MaxDepth { get; init; } = 64; +} diff --git a/src/EventsModel.Meta/MessageDescription.cs b/src/EventsModel.Meta/MessageDescription.cs new file mode 100644 index 0000000..f461e2e --- /dev/null +++ b/src/EventsModel.Meta/MessageDescription.cs @@ -0,0 +1,8 @@ +using System.Text.Json.Nodes; + +namespace Skyware.Lis.EventsModel.Meta; + +/// +/// Self-contained description suitable for a describe_message MCP tool. +/// +public sealed record MessageDescription(MessageTypeInfo MessageType, JsonObject Schema, IReadOnlyList Examples); diff --git a/src/EventsModel.Meta/MessageExample.cs b/src/EventsModel.Meta/MessageExample.cs new file mode 100644 index 0000000..94be9ee --- /dev/null +++ b/src/EventsModel.Meta/MessageExample.cs @@ -0,0 +1,8 @@ +using System.Text.Json.Nodes; + +namespace Skyware.Lis.EventsModel.Meta; + +/// +/// An explicitly synthetic, schema-derived example; not a real clinical event. +/// +public sealed record MessageExample(string Description, JsonNode Value); diff --git a/src/EventsModel.Meta/MessageExplanation.cs b/src/EventsModel.Meta/MessageExplanation.cs new file mode 100644 index 0000000..9135cba --- /dev/null +++ b/src/EventsModel.Meta/MessageExplanation.cs @@ -0,0 +1,12 @@ +using System.Text.Json; + +namespace Skyware.Lis.EventsModel.Meta; + +/// +/// Original parsed JSON and documentation for every compatible candidate, without guessing. +/// +public sealed record MessageExplanation( + MessageMatchStatus Status, + JsonElement? Message, + IReadOnlyList Candidates, + IReadOnlyList Errors); diff --git a/src/EventsModel.Meta/MessageMatchStatus.cs b/src/EventsModel.Meta/MessageMatchStatus.cs new file mode 100644 index 0000000..938c7ca --- /dev/null +++ b/src/EventsModel.Meta/MessageMatchStatus.cs @@ -0,0 +1,35 @@ +using System.Text.Json.Serialization; + +namespace Skyware.Lis.EventsModel.Meta; + +/// +/// Recognition outcome. Matched means one compatible type, not proof of the producer's intent. +/// +[JsonConverter(typeof(JsonStringEnumConverter))] +public enum MessageMatchStatus +{ + /// + /// Exactly one type is compatible. + /// + Matched, + /// + /// Multiple types are compatible; no type is selected. + /// + Ambiguous, + /// + /// No type is compatible. + /// + NoMatch, + /// + /// Malformed JSON, duplicate properties, excessive size or excessive nesting. + /// + InvalidJson, + /// + /// JSON is not an object, or does not satisfy the explicitly selected type. + /// + InvalidMessage, + /// + /// A configured discriminator is present but its value is not registered. + /// + UnknownDiscriminator +} diff --git a/src/EventsModel.Meta/MessageParseException.cs b/src/EventsModel.Meta/MessageParseException.cs new file mode 100644 index 0000000..35f9860 --- /dev/null +++ b/src/EventsModel.Meta/MessageParseException.cs @@ -0,0 +1,18 @@ +namespace Skyware.Lis.EventsModel.Meta; + +/// +/// Thrown when parsing cannot select exactly one valid message type. +/// +public sealed class MessageParseException : Exception +{ + /// + /// The recognition result, including candidates and validation errors. + /// + public MessageExplanation Explanation { get; } + + /// + /// Creates an exception preserving the recognition result. + /// + public MessageParseException(MessageExplanation explanation) + : base($"Message cannot be parsed: {explanation.Status}.") => Explanation = explanation; +} diff --git a/src/EventsModel.Meta/MessageTypeInfo.cs b/src/EventsModel.Meta/MessageTypeInfo.cs new file mode 100644 index 0000000..ac42824 --- /dev/null +++ b/src/EventsModel.Meta/MessageTypeInfo.cs @@ -0,0 +1,6 @@ +namespace Skyware.Lis.EventsModel.Meta; + +/// +/// Discoverable message type, its XML documentation and default broker address. +/// +public sealed record MessageTypeInfo(string Type, string ClrType, string Description, string DefaultAddress); diff --git a/src/EventsModel.Meta/ModelDocumentation.cs b/src/EventsModel.Meta/ModelDocumentation.cs new file mode 100644 index 0000000..b89a801 --- /dev/null +++ b/src/EventsModel.Meta/ModelDocumentation.cs @@ -0,0 +1,101 @@ +using System.Reflection; +using System.Text.RegularExpressions; +using System.Xml.Linq; + +namespace Skyware.Lis.EventsModel.Meta; + +/// +/// Reads the model's embedded compiler-generated XML documentation and renders it as plain text. +/// +internal sealed class ModelDocumentation +{ + /// + /// Documentation entries indexed by their compiler-generated member IDs. + /// + private readonly Dictionary members; + + /// + /// Loads and indexes the embedded model documentation. + /// + /// + /// The embedded documentation resource is missing. + /// + public ModelDocumentation() + { + using var stream = typeof(ModelDocumentation).Assembly.GetManifestResourceStream( + "Skyware.Lis.EventsModel.Meta.ModelDocumentation.xml") + ?? throw new InvalidOperationException("Embedded model XML documentation is missing."); + members = XDocument.Load(stream).Descendants("member") + .ToDictionary(x => (string)x.Attribute("name")!, StringComparer.Ordinal); + } + + /// + /// Renders the summary and remarks for a model type, field, or property, resolving supported inheritdoc references. + /// + /// + /// The reflected model member whose documentation is requested. + /// + /// + /// The rendered description, or an empty string when no supported documentation is available. + /// Summary and remarks are separated by a blank line. + /// + public string Describe(MemberInfo member) + { + var prefix = member is Type ? "T:" : member is FieldInfo ? "F:" : "P:"; + var id = prefix + (member is Type t ? t.FullName : member.DeclaringType!.FullName + "." + member.Name); + if (!members.TryGetValue(id, out var doc)) return ""; + var parts = new[] { doc.Element("summary"), doc.Element("remarks") } + .Where(x => x is not null).Select(x => Render(x!)).Where(x => x.Length > 0).ToArray(); + if (parts.Length > 0) return string.Join("\n\n", parts); + if (doc.Element("inheritdoc") is { } inherit) + { + var reference = (string?)inherit.Attribute("cref"); + if (reference is not null && members.TryGetValue(reference, out var inherited)) + return string.Join("\n\n", new[] { inherited.Element("summary"), inherited.Element("remarks") } + .Where(x => x is not null).Select(x => Render(x!))); + var baseType = (member as Type)?.BaseType ?? member.DeclaringType?.BaseType; + if (baseType is not null) + { + MemberInfo? baseMember = member is Type ? baseType : baseType.GetProperty(member.Name); + if (baseMember is not null) return Describe(baseMember); + } + } + return ""; + } + + /// + /// Converts an XML documentation element to plain text, rendering references and normalizing whitespace. + /// + /// + /// The documentation element to render. + /// + /// + /// The rendered text with surrounding whitespace removed. + /// + private static string Render(XElement element) + { + string Walk(XNode node) => node switch + { + XText text => text.Value, + XElement e when e.Name.LocalName is "see" or "seealso" => e.Value.Length > 0 ? e.Value + : (string?)e.Attribute("langword") ?? Reference((string?)e.Attribute("cref")) + ?? (string?)e.Attribute("href") ?? "", + XElement e when e.Name.LocalName is "paramref" or "typeparamref" => (string?)e.Attribute("name") ?? "", + XElement e => " " + string.Concat(e.Nodes().Select(Walk)) + " ", + _ => "" + }; + return Regex.Replace(string.Concat(element.Nodes().Select(Walk)), @"\s+", " ").Trim(); + } + + /// + /// Converts a compiler-generated reference ID to a readable name relative to the model namespace. + /// + /// + /// The reference ID, or null when no reference is present. + /// + /// + /// The readable reference name, or null when the input is null. + /// + private static string? Reference(string? value) => value is null ? null + : value[(value.IndexOf(':') + 1)..].Replace("Skyware.Lis.EventsModel.", "", StringComparison.Ordinal); +} diff --git a/src/EventsModel.Meta/README.md b/src/EventsModel.Meta/README.md new file mode 100644 index 0000000..39d7fcc --- /dev/null +++ b/src/EventsModel.Meta/README.md @@ -0,0 +1,143 @@ +# EventsModel.Meta + +`Skyware.Lis.EventsModel.Meta` provides documented JSON Schema 2020-12 documents, +message discovery, recognition and parsing for `Skyware.Lis.EventsModel`. +It targets .NET 8, 9 and 10 and is independent of any MCP server SDK. + +## Usage + +```csharp +using Skyware.Lis.EventsModel.Meta; + +var catalog = new MessageCatalog(); // Reuse across requests. +var types = catalog.ListMessageTypes(); +var description = catalog.DescribeMessage("Instruments.ResultApproval"); +var schemaJson = description.Schema.ToJsonString(); + +var explanation = catalog.ExplainMessage("""{"ShipmentId":42,"IsSent":true}"""); +if (explanation.Status == MessageMatchStatus.Matched) +{ + var message = catalog.ParseMessage(explanation.Message!.Value.GetRawText()); +} + +// When the transport supplies a reliable message type: +var approved = catalog.ParseMessage("""{"Data":null}""", "Instruments.ResultApproval"); + +// Supporting objects and enums can also be described independently. +var resultSchema = catalog.GetSchema(); +``` + +| MCP tool | Library call | +| --- | --- | +| `list_message_types()` | `catalog.ListMessageTypes()` | +| `describe_message(type)` | `catalog.DescribeMessage(type)` | +| `explain_message(json)` | `catalog.ExplainMessage(json)` | + +The returned records, schemas and payloads can be serialized with `System.Text.Json`. +Match statuses serialize as readable strings. An agent consuming the tool responses +does not need access to the model assembly or source code. + +## Schemas and documentation + +- Compiler-produced model XML documentation is embedded in the Meta assembly. + NuGet consumers need no source files or sidecar XML documentation. +- Schemas follow `System.Text.Json` metadata: inheritance, nested objects, + collections, nullable values, ignored and read-only properties. `summary` and + `remarks` become `description`; XML references are rendered as text. + Descriptions retain their source language. +- Enum members are documented in `x-enumDescriptions`, preserving distinctions + such as technical versus medical validation. Enums retain their numeric wire format. +- Examples are deterministic **synthetic structural examples**, not real clinical + data, medical guidance or complete production events. +- Schemas are standalone, using local references where necessary. Returned + documents are copies; editing them does not alter the catalog. + +## Wire format and recognition + +Names default to **PascalCase**, matching the model's current JSON contract. +CamelCase can be selected explicitly: + +```csharp +var catalog = new MessageCatalog(new MessageCatalogOptions +{ + PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase +}); +``` + +Names are case-sensitive. Unknown properties, including nested ones, are rejected +(`additionalProperties: false` for object contracts). This strict recognition +policy avoids misidentification caused by silently dropping fields. Future +producer fields can therefore produce `NoMatch` until the consumer updates its model. + +Fields are required only when required by the serialization contract. No business +requirements are invented: `{}` and messages with only common fields are ambiguous. +A unique match means compatibility with this catalog, not proof of producer intent. +`Instruments.Result` and `Instruments.ResultApproval` have identical shapes, so both +are returned without an external type or discriminator. Candidates are never ranked. + +Recognition returns `Matched`, `Ambiguous`, `NoMatch`, `InvalidJson`, +`InvalidMessage`, or `UnknownDiscriminator`. It includes the original parsed JSON +and documentation for **all** compatible candidates. When no type matches, errors +identify the candidate and location. Schema errors use JSON Pointers; deserialization +errors use System.Text.Json paths. + +`ParseMessage` validates before deserializing and throws `MessageParseException` +containing the explanation if it cannot select one valid type. Explicit type names +accept a relative model ID, full CLR name or unambiguous simple name. Arbitrary CLR +types supplied by input are never loaded. + +JSON Schema `format` values remain annotations. Recognition also runs the .NET +deserializer to check actual CLR constraints (integer ranges, dates, etc.). This +accepts offset-free timestamps serialized from `DateTimeKind.Unspecified` and +rejects invalid dates. It does not validate clinical or business rules. + +Input defaults: 1 MiB UTF-8 and 64 nesting levels, configurable through +`MaxMessageBytes` and `MaxDepth`. Duplicate property names at any level are rejected. + +## Optional discriminator + +The model's current `JsonDerivedType` attributes do not declare discriminator +values. Configure a transport convention explicitly when producers supply one: + +```csharp +var catalog = new MessageCatalog(new MessageCatalogOptions +{ + DiscriminatorPropertyName = "$type", + DiscriminatorMappings = new Dictionary + { + ["result"] = "Instruments.Result", + ["approved-result"] = "Instruments.ResultApproval" + } +}); +var message = catalog.ParseMessage("""{"$type":"approved-result","Data":null}"""); +``` + +Only registered string values are accepted. The discriminator appears in the +schema and original JSON, and is removed only for CLR deserialization. Unknown +values never fall back to guessing. A known discriminator still requires a valid +payload; conflicts with an explicitly requested type are rejected. When absent, +structural matching is used. These options do not modify producer serialization. + +## Existing model details + +The schemas describe the actual wire contract, including these existing details: + +- `Results.ResultsSet.Results` is non-public and is not serialized. +- Concrete `DefaultAddress` overrides are serialized despite `[JsonIgnore]` on + the abstract base property. They are marked read-only and also appear in + discovery metadata. Their input values do not select a type. +- Missing CLR properties retain their initializers (IDs, timestamps, defaults) + when parsed. The original JSON in `ExplainMessage` is never filled in or changed. + +## Build and test + +```sh +dotnet test tests/EventsModel.Meta.Tests/EventsModel.Meta.Tests.csproj -c Release -p:GeneratePackageOnBuild=false +dotnet pack src/EventsModel.Meta/EventsModel.Meta.csproj -c Release -p:GeneratePackageOnBuild=false -o artifacts +``` + +The package depends on `Skyware.Lis.EventsModel` at its project-reference version. +The existing publishing workflow does not publish the new Meta package automatically. + +References: [System.Text.Json schema exporter](https://learn.microsoft.com/dotnet/standard/serialization/system-text-json/extract-schema), +[JsonSchema.Net](https://docs.json-everything.net/schema/basics/). diff --git a/src/EventsModel.Meta/SchemaEntry.cs b/src/EventsModel.Meta/SchemaEntry.cs new file mode 100644 index 0000000..9396dc4 --- /dev/null +++ b/src/EventsModel.Meta/SchemaEntry.cs @@ -0,0 +1,6 @@ +using System.Text.Json.Nodes; +using Json.Schema; + +namespace Skyware.Lis.EventsModel.Meta; + +internal sealed record SchemaEntry(JsonObject Schema, JsonSchema Validator); diff --git a/src/EventsModel.Meta/SchemaExample.cs b/src/EventsModel.Meta/SchemaExample.cs new file mode 100644 index 0000000..813b45c --- /dev/null +++ b/src/EventsModel.Meta/SchemaExample.cs @@ -0,0 +1,60 @@ +using System.Text.Json.Nodes; + +namespace Skyware.Lis.EventsModel.Meta; + +internal static class SchemaExample +{ + public static JsonNode Create(JsonObject schema) => Build(schema, schema, 0) + ?? throw new InvalidOperationException("A message example must be an object."); + + private static JsonNode? Build(JsonNode schema, JsonNode root, int depth) + { + if (depth > 32) throw new InvalidOperationException("Example schema exceeds supported nesting depth."); + if (schema is not JsonObject obj) return null; + if (obj["$ref"] is JsonValue reference) + { + var pointer = reference.GetValue(); + if (!pointer.StartsWith('#')) throw new InvalidOperationException("Only local schema references are supported."); + var target = root; + foreach (var segment in pointer[1..].Split('/', StringSplitOptions.RemoveEmptyEntries)) + { + var key = Uri.UnescapeDataString(segment).Replace("~1", "/").Replace("~0", "~"); + target = target is JsonArray array ? array[int.Parse(key)]! : target[key]!; + } + return Build(target, root, depth + 1); + } + if (obj["const"] is { } constant) return constant.DeepClone(); + if (obj["enum"] is JsonArray values) return values.FirstOrDefault(x => x is not null)?.DeepClone(); + if ((obj["anyOf"] ?? obj["oneOf"]) is JsonArray alternatives) + { + var branch = alternatives.FirstOrDefault(x => x is JsonObject && x["type"]?.ToJsonString() != "\"null\""); + if (branch is not null) return Build(branch, root, depth + 1); + } + var type = obj["type"] is JsonArray types + ? types.Select(x => x!.GetValue()).FirstOrDefault(x => x != "null") + : obj["type"]?.GetValue(); + switch (type) + { + case "object": + var result = new JsonObject(); + if (obj["properties"] is JsonObject properties) + foreach (var property in properties) result[property.Key] = Build(property.Value!, root, depth + 1); + return result; + case "array": + return obj["items"] is { } items ? new JsonArray(Build(items, root, depth + 1)) : new JsonArray(); + case "integer": + case "number": return JsonValue.Create(0); + case "boolean": return JsonValue.Create(false); + case "string": return JsonValue.Create(obj["format"]?.GetValue() switch + { + "date-time" => "2000-01-01T00:00:00Z", + "date" => "2000-01-01", + "time" => "00:00:00Z", + "uuid" => "00000000-0000-0000-0000-000000000000", + "duration" => "P0D", + _ => "example" + }); + default: return null; + } + } +} diff --git a/src/EventsModel.Meta/ValidationIssue.cs b/src/EventsModel.Meta/ValidationIssue.cs new file mode 100644 index 0000000..b638b3a --- /dev/null +++ b/src/EventsModel.Meta/ValidationIssue.cs @@ -0,0 +1,6 @@ +namespace Skyware.Lis.EventsModel.Meta; + +/// +/// A validation error, optionally associated with a candidate and a JSON Pointer. +/// +public sealed record ValidationIssue(string? Type, string Path, string Message); diff --git a/src/EventsModel/BaseMessage.cs b/src/EventsModel/BaseMessage.cs index dcc64cd..28d4b98 100644 --- a/src/EventsModel/BaseMessage.cs +++ b/src/EventsModel/BaseMessage.cs @@ -21,6 +21,7 @@ namespace Skyware.Lis.EventsModel; [JsonDerivedType(typeof(BgNra.InsuranceCheck))] [JsonDerivedType(typeof(BgNhis.ReferralAction))] [JsonDerivedType(typeof(BgNhis.Session))] +[JsonDerivedType(typeof(Catalog.EntryChange))] public abstract class BaseMessage { diff --git a/src/EventsModel/BgNhis/BgDoctor.cs b/src/EventsModel/BgNhis/BgDoctor.cs index 282cde7..c999be0 100644 --- a/src/EventsModel/BgNhis/BgDoctor.cs +++ b/src/EventsModel/BgNhis/BgDoctor.cs @@ -1,6 +1,4 @@ -// Ignore Spelling: bg - -using Skyware.Lis.EventsModel.Common; +using Skyware.Lis.EventsModel.Common; namespace Skyware.Lis.EventsModel.BgNhis; diff --git a/src/EventsModel/BgNhis/Referral.cs b/src/EventsModel/BgNhis/Referral.cs index 38eaf30..53334f5 100644 --- a/src/EventsModel/BgNhis/Referral.cs +++ b/src/EventsModel/BgNhis/Referral.cs @@ -2,8 +2,6 @@ using System; using System.Collections.Generic; -// Ignore Spelling: nrn lrn - namespace Skyware.Lis.EventsModel.BgNhis; /// diff --git a/src/EventsModel/BgNhis/ReferralAction.cs b/src/EventsModel/BgNhis/ReferralAction.cs index 1830f7f..0500861 100644 --- a/src/EventsModel/BgNhis/ReferralAction.cs +++ b/src/EventsModel/BgNhis/ReferralAction.cs @@ -1,6 +1,4 @@ -// Ignore Spelling: bg - -namespace Skyware.Lis.EventsModel.BgNhis; +namespace Skyware.Lis.EventsModel.BgNhis; /// /// Occurs when action with a is made diff --git a/src/EventsModel/BgNhis/Session.cs b/src/EventsModel/BgNhis/Session.cs index ffd32c7..a87863c 100644 --- a/src/EventsModel/BgNhis/Session.cs +++ b/src/EventsModel/BgNhis/Session.cs @@ -1,6 +1,4 @@ -// Ignore Spelling: bg uin - -namespace Skyware.Lis.EventsModel.BgNhis; +namespace Skyware.Lis.EventsModel.BgNhis; /// /// Represent attempt for creation of session in NHIS diff --git a/src/EventsModel/Catalog/EntryChange.cs b/src/EventsModel/Catalog/EntryChange.cs new file mode 100644 index 0000000..acc4c54 --- /dev/null +++ b/src/EventsModel/Catalog/EntryChange.cs @@ -0,0 +1,55 @@ +using Skyware.Lis.EventsModel.Common; + +namespace Skyware.Lis.EventsModel.Catalog; + +/// +/// Occurs when reference data (a catalog entry) has been created, changed or deleted. +/// +/// +/// The message says which entry changed, not how: it carries no property values, so it is safe to broadcast and +/// subscribers that cache LIS data read the current state from the database. Delivery is not guaranteed: a message may +/// be lost, repeated or arrive out of order, and changes made outside the emitting application (other LIS applications, +/// SQL scripts) emit nothing, so caches still need an expiry or a periodic refresh. Because a subscriber re-reads the +/// entry, a repeated or late message is harmless. Use to handle the messages of one save +/// together. +/// +public class EntryChange : BaseMessage +{ + + /// + public override string DefaultAddress => "topic://catalog/entry"; + + /// + /// Primary key of the entry in the database, or null when the change concerns many entries of the table at once + /// (e.g. a cascading or bulk delete or an import), which subscribers treat as "the whole table may have changed". + /// + /// + /// A single key is its invariant text, e.g. "42" or "general.robin-url". A composite key is a JSON array of its + /// values in the key order of the LIS Model type, e.g. "[12,5]". + /// + public string EntryId { get; set; } + + /// + /// Name of the database table where the entry is stored, without the schema, e.g. "Tests" or "SampleTypes". + /// + public string TableName { get; set; } + + /// + /// Fully qualified name of the entry's type in the LIS Model library, e.g. "Skyware.Lis.Model.Test". + /// + public string TypeName { get; set; } + + /// + /// What happened to the entry, according to : "Created", "Updated" or "Deleted". + /// + /// + /// Without it is "Updated": entries of the table may have been created, changed or deleted. + /// + public string EventType { get; set; } = CommonEvents.UPDATED; + + /// + /// Identifier (GUID) shared by every message of one save, e.g. a record and its child entries saved together. + /// + public string OperationId { get; set; } + +} diff --git a/src/EventsModel/Catalog/PropertyChange.cs b/src/EventsModel/Catalog/PropertyChange.cs new file mode 100644 index 0000000..5f6071a --- /dev/null +++ b/src/EventsModel/Catalog/PropertyChange.cs @@ -0,0 +1,41 @@ +namespace Skyware.Lis.EventsModel.Catalog; + +/// +/// Change desription in catalog data. +/// +public class PropertyChange +{ + + /// + /// Name of the column in the database table where the property is stored, e.g. "Name", "IsDerived", etc. + /// + public string ColumnName { get; set; } + + /// + /// Name of the property in LIS Model library that has been changed, e.g. "Name", "IsDerived", etc. + /// + public string PropertyName { get; set; } + + /// + /// Old value of the property before the change. + /// + /// + /// For non-string types, consider serializing the value to a string format as follows: + /// + /// int, byte, short, long"42" + /// decimal, money"3.14" (invariant culture, up to last significant digit) + /// boolean, bit"true" or "false" (case-insensitive) + /// + /// Same applies to property. + /// + public string OldValue { get; set; } + + /// + /// New value of the property after the change. + /// + /// + /// See for serialization recommendations for non-string types. + /// + public string NewValue { get; set; } + +} diff --git a/src/EventsModel/EventsModel.csproj b/src/EventsModel/EventsModel.csproj index 42826ec..ff4cb2c 100644 --- a/src/EventsModel/EventsModel.csproj +++ b/src/EventsModel/EventsModel.csproj @@ -7,7 +7,7 @@ Skyware.Lis.EventsModel Skyware.Lis.EventsModel - 0.9.0 + 0.9.1 Mikhail Kalatchev Skyware.Lis.EventsModel diff --git a/src/EventsModel/SampleTracking/SampleShipment.cs b/src/EventsModel/SampleTracking/SampleShipment.cs index 32da05c..7bb14ae 100644 --- a/src/EventsModel/SampleTracking/SampleShipment.cs +++ b/src/EventsModel/SampleTracking/SampleShipment.cs @@ -53,7 +53,7 @@ public class SampleShipment : BaseMessage /// /// Identifier of the courier responsible for the shipment - /// + /// public int? CourierId { get; set; } /// diff --git a/src/EventsModelDocs/EventsModelDocs.csproj b/src/EventsModelDocs/EventsModelDocs.csproj index 8d145ca..06e438c 100644 --- a/src/EventsModelDocs/EventsModelDocs.csproj +++ b/src/EventsModelDocs/EventsModelDocs.csproj @@ -1,21 +1,21 @@  - + Exe net10.0 enable enable - + - + all runtime; build; native; contentfiles; analyzers; buildtransitive - + \ No newline at end of file diff --git a/src/EventsModelDocs/articles/addresses.md b/src/EventsModelDocs/articles/addresses.md index dc6db53..743ead8 100644 --- a/src/EventsModelDocs/articles/addresses.md +++ b/src/EventsModelDocs/articles/addresses.md @@ -20,6 +20,20 @@ The `ResultsSet` event occurs when one or more results are modified or deleted. | Events | One or more Visit's results are changed | | Applications | iLab | +## Catalog + +### Entry Change +The `EntryChange` event occurs when reference data (a catalog entry such as a test, a sample type or a doctor) is created, +changed or deleted. It names the table, the LIS Model type and the key of the entry, without property values, so that +applications caching LIS data know what to refresh. Without a key, the whole table may have changed. + +| Key | Value | +|:--- |:--- | +| Address | `topic://catalog/entry` | +| Object | `Skyware.Lis.EventsModel.Catalog.EntryChange` | +| Events | Created, Updated, Deleted (see `CommonEvents`) | +| Applications | LisAdmin | + ## Instruments ### Query diff --git a/tests/EventsModel.Meta.Tests/EventsModel.Meta.Tests.csproj b/tests/EventsModel.Meta.Tests/EventsModel.Meta.Tests.csproj new file mode 100644 index 0000000..e226cd0 --- /dev/null +++ b/tests/EventsModel.Meta.Tests/EventsModel.Meta.Tests.csproj @@ -0,0 +1,19 @@ + + + + net8.0;net9.0;net10.0 + enable + enable + false + true + + + + + + + + + + + diff --git a/tests/EventsModel.Meta.Tests/MessageCatalogTests.cs b/tests/EventsModel.Meta.Tests/MessageCatalogTests.cs new file mode 100644 index 0000000..ade8095 --- /dev/null +++ b/tests/EventsModel.Meta.Tests/MessageCatalogTests.cs @@ -0,0 +1,264 @@ +using System.Text.Json; +using System.Text.Json.Nodes; +using Json.Schema; +using Skyware.Lis.EventsModel; +using Skyware.Lis.EventsModel.Meta; +using Skyware.Lis.EventsModel.Visits; +using Skyware.Lis.EventsModel.Results; +using InstrumentResult = Skyware.Lis.EventsModel.Instruments.Result; + +namespace EventsModel.Meta.Tests; + +public class MessageCatalogTests +{ + private readonly MessageCatalog catalog = new(); + + [Fact] + public void DiscoversAllConcreteMessagesAndIncludesDescriptionsAndAddresses() + { + var types = catalog.ListMessageTypes(); + var expected = typeof(BaseMessage).Assembly.GetExportedTypes() + .Where(t => !t.IsAbstract && typeof(BaseMessage).IsAssignableFrom(t)).Select(t => t.FullName).Order().ToArray(); + Assert.Equal(expected, types.Select(t => t.ClrType).Order().ToArray()); + Assert.Equal(15, types.Count); + Assert.All(types, t => { Assert.NotEmpty(t.Description); Assert.StartsWith("topic://", t.DefaultAddress); }); + } + + [Fact] + public void SchemasContainInheritedAndNestedDocumentationAndRemarks() + { + var schema = catalog.DescribeMessage("Visits.Sale").Schema; + var properties = schema["properties"]!.AsObject(); + Assert.Equal("https://json-schema.org/draft/2020-12/schema", schema["$schema"]!.GetValue()); + Assert.Contains("GUID", properties["Id"]!["description"]!.GetValue()); + Assert.Contains("does not report funds", properties["Funding"]!["description"]!.GetValue()); + Assert.Contains("has been removed", properties["Diagnoses"]!["description"]!.GetValue()); + Assert.Contains("GivenName", schema.ToJsonString()); + Assert.Contains("First (given) name", schema.ToJsonString()); + Assert.DoesNotContain("()); + Assert.True(properties["LocalEventTime"]!["readOnly"]!.GetValue()); + Assert.Contains("null", properties["Funding"]!.ToJsonString()); + Assert.False(schema["additionalProperties"]!.GetValue()); + } + + [Fact] + public void IncludesEnumValueSemantics() + { + var schema = catalog.GetSchema(); + var descriptions = schema["properties"]!["Status"]!["x-enumDescriptions"]!.AsArray(); + var preliminary = descriptions.Single(x => x!["name"]!.GetValue() == "Preliminary")!; + Assert.Equal(2, preliminary["value"]!.GetValue()); + Assert.Contains("not ready for reporting", preliminary["description"]!.GetValue()); + } + + [Fact] + public void CanExportEveryPublicModelClassAndEnum() + { + foreach (var type in typeof(BaseMessage).Assembly.GetExportedTypes().Where(t => t.IsClass || t.IsEnum)) + Assert.NotNull(catalog.GetSchema(type)["$schema"]); + } + + [Fact] + public void SchemaFollowsActualSerializationIncludingNonPublicAndIgnoredMembers() + { + var schema = catalog.GetSchema(); + Assert.Null(schema["properties"]!["Results"]); // Currently private in the model: do not invent wire fields. + foreach (var info in catalog.ListMessageTypes()) + { + var type = typeof(BaseMessage).Assembly.GetType(info.ClrType)!; + var message = (BaseMessage)Activator.CreateInstance(type)!; + var json = JsonSerializer.Serialize(message); + using var serialized = JsonDocument.Parse(json); + Assert.Equal(serialized.RootElement.EnumerateObject().Select(p => p.Name).Order(), + catalog.DescribeMessage(info.Type).Schema["properties"]!.AsObject().Select(p => p.Key).Order()); + Assert.IsType(type, catalog.ParseMessage(json, info.Type)); + } + } + + [Fact] + public void EverySyntheticExampleIsDeterministicSchemaValidAndParseable() + { + foreach (var info in catalog.ListMessageTypes()) + { + var description = catalog.DescribeMessage(info.Type); + var example = Assert.Single(description.Examples); + Assert.Contains("Synthetic", example.Description); + using var json = JsonDocument.Parse(example.Value.ToJsonString()); + var validator = JsonSchema.FromText(description.Schema.ToJsonString(), new BuildOptions { SchemaRegistry = new() }); + Assert.True(validator.Evaluate(json.RootElement, new EvaluationOptions { RequireFormatValidation = true }).IsValid, info.Type); + Assert.Equal(info.ClrType, catalog.ParseMessage(example.Value.ToJsonString(), info.Type).GetType().FullName); + Assert.Equal(example.Value.ToJsonString(), catalog.DescribeMessage(info.Type).Examples[0].Value.ToJsonString()); + } + } + + [Fact] + public void RecognizesUniqueShapeAndPreservesOriginalPayload() + { + const string json = """{"ShipmentId":42,"IsSent":true,"Sender":{"Id":7}}"""; + var result = catalog.ExplainMessage(json); + Assert.Equal(MessageMatchStatus.Matched, result.Status); + Assert.Equal("SampleTracking.SampleShipment", Assert.Single(result.Candidates).MessageType.Type); + Assert.Equal(42, result.Message!.Value.GetProperty("ShipmentId").GetInt32()); + var parsed = Assert.IsType(catalog.ParseMessage(json)); + Assert.Equal(42, parsed.ShipmentId); + } + + [Fact] + public void IdenticalResultAndApprovalShapesRemainAmbiguous() + { + var json = catalog.DescribeMessage("Instruments.Result").Examples[0].Value.ToJsonString(); + var result = catalog.ExplainMessage(json); + Assert.Equal(MessageMatchStatus.Ambiguous, result.Status); + Assert.Equal(new[] { "Instruments.Result", "Instruments.ResultApproval" }, result.Candidates.Select(c => c.MessageType.Type)); + var error = Assert.Throws(() => catalog.ParseMessage(json)); + Assert.Equal(MessageMatchStatus.Ambiguous, error.Explanation.Status); + Assert.IsType(catalog.ParseMessage(json, "Instruments.Result")); + } + + [Theory] + [InlineData("{}")] + [InlineData("{\"Id\":\"shared\"}")] + public void SparseMessagesAreNotGuessed(string json) + { + var result = catalog.ExplainMessage(json); + Assert.Equal(MessageMatchStatus.Ambiguous, result.Status); + Assert.Equal(15, result.Candidates.Count); + } + + [Theory] + [InlineData("{\"ShipmentId\":\"not-a-number\"}")] + [InlineData("{\"ShipmentId\":1.5}")] + [InlineData("{\"ShipmentId\":9999999999999999999}")] + [InlineData("{\"ShipmentId\":1,\"Sent\":\"not-a-date\"}")] + [InlineData("{\"ShipmentId\":1,\"Sender\":{\"Id\":\"wrong\"}}")] + [InlineData("{\"unknown\":1}")] + [InlineData("{\"shipmentId\":1}")] + public void RejectsTypeMismatchesUnknownFieldsAndClrOverflow(string json) + { + var result = catalog.ExplainMessage(json); + Assert.Equal(MessageMatchStatus.NoMatch, result.Status); + Assert.NotEmpty(result.Errors); + Assert.Empty(result.Candidates); + } + + [Theory] + [InlineData("not JSON")] + [InlineData("{\"Id\":1,\"Id\":2}")] + [InlineData("{\"Sender\":{\"Id\":1,\"Id\":2}}")] + [InlineData("{\"Samples\":[{\"Id\":1,\"Id\":2}]}")] + public void RejectsMalformedOrDuplicateJson(string json) => + Assert.Equal(MessageMatchStatus.InvalidJson, catalog.ExplainMessage(json).Status); + + [Theory] + [InlineData("null")] + [InlineData("[]")] + [InlineData("42")] + public void RequiresTopLevelObject(string json) => + Assert.Equal(MessageMatchStatus.InvalidMessage, catalog.ExplainMessage(json).Status); + + [Fact] + public void RespectsPayloadAndDepthLimits() + { + var limited = new MessageCatalog(new() { MaxMessageBytes = 20, MaxDepth = 2 }); + Assert.Equal(MessageMatchStatus.InvalidJson, limited.ExplainMessage("{\"Id\":\"" + new string('я', 10) + "\"}").Status); + Assert.Equal(MessageMatchStatus.InvalidJson, limited.ExplainMessage("{\"a\":{\"b\":{}}}").Status); + } + + [Fact] + public void OptionalDiscriminatorSelectsOnlyRegisteredTypesAndStillValidates() + { + var configured = DiscriminatedCatalog(); + var result = configured.ExplainMessage("""{"$type":"result","Data":null}"""); + Assert.Equal(MessageMatchStatus.Matched, result.Status); + Assert.Equal("Instruments.Result", Assert.Single(result.Candidates).MessageType.Type); + Assert.IsType(configured.ParseMessage("""{"$type":"result","Data":null}""")); + Assert.Equal(MessageMatchStatus.UnknownDiscriminator, configured.ExplainMessage("""{"$type":"System.IO.File"}""").Status); + Assert.Equal(MessageMatchStatus.UnknownDiscriminator, configured.ExplainMessage("""{"$type":42}""").Status); + Assert.Equal(MessageMatchStatus.InvalidMessage, configured.ExplainMessage("""{"$type":"result","Data":42}""").Status); + Assert.Equal(MessageMatchStatus.Ambiguous, configured.ExplainMessage("{}").Status); + Assert.Throws(() => configured.ParseMessage("""{"$type":"result"}""", "Instruments.Query")); + var description = configured.DescribeMessage("Instruments.Result"); + Assert.Equal("result", description.Schema["properties"]!["$type"]!["enum"]![0]!.GetValue()); + Assert.IsType(configured.ParseMessage(description.Examples[0].Value.ToJsonString())); + } + + [Fact] + public void CamelCaseIsExplicitAndConsistentAcrossSchemasAndParsing() + { + var camel = new MessageCatalog(new() { PropertyNamingPolicy = JsonNamingPolicy.CamelCase }); + Assert.NotNull(camel.DescribeMessage("Visits.Sale").Schema["properties"]!["saleId"]); + Assert.Equal(MessageMatchStatus.Matched, camel.ExplainMessage("""{"shipmentId":1}""").Status); + Assert.Equal(MessageMatchStatus.NoMatch, camel.ExplainMessage("""{"ShipmentId":1}""").Status); + } + + [Fact] + public void ReturnedDocumentsCannotMutateCachedSchemas() + { + var description = catalog.DescribeMessage("Visits.Sale"); + description.Schema["properties"] = new JsonObject(); + description.Examples[0].Value["SaleId"] = 999; + Assert.NotNull(catalog.DescribeMessage("Visits.Sale").Schema["properties"]!["SaleId"]); + Assert.Equal(0, catalog.DescribeMessage("Visits.Sale").Examples[0].Value["SaleId"]!.GetValue()); + } + + [Fact] + public void OnlyKnownModelTypesAreAccepted() + { + Assert.Throws(() => catalog.GetSchema(typeof(string))); + Assert.Throws(() => catalog.DescribeMessage("System.IO.File")); + Assert.Equal("Visits.Sale", catalog.DescribeMessage(typeof(Sale).FullName!).MessageType.Type); + Assert.Equal("Visits.Sale", catalog.DescribeMessage("Sale").MessageType.Type); + Assert.Throws(() => new MessageCatalog(new() { DiscriminatorPropertyName = "Id" })); + Assert.Throws(() => new MessageCatalog(new() { DiscriminatorMappings = new Dictionary { ["x"] = "Sale" } })); + } + + [Fact] + public void DocumentationIsEmbeddedAndCourierDescriptionSurvivesCompilation() + { + Assert.Contains("Skyware.Lis.EventsModel.Meta.ModelDocumentation.xml", typeof(MessageCatalog).Assembly.GetManifestResourceNames()); + var schema = catalog.DescribeMessage("SampleTracking.SampleShipment").Schema; + Assert.Contains("courier", schema["properties"]!["CourierId"]!["description"]!.GetValue()); + } + + [Fact] + public void HandlesNestedArraysAndReportsTheirErrorPaths() + { + var result = catalog.ExplainMessage("""{"ShipmentId":1,"Samples":[{"Id":"wrong"}]}"""); + Assert.Equal(MessageMatchStatus.NoMatch, result.Status); + Assert.Contains(result.Errors, e => e.Type == "SampleTracking.SampleShipment" && e.Path.StartsWith("/Samples/0")); + } + + [Fact] + public void AcceptsUnspecifiedDateTimeAndNullableFieldsWithoutInventingRequiredProperties() + { + var result = catalog.ParseMessage("""{"ShipmentId":1,"Sent":"2026-10-31T12:00:00","Received":null}"""); + var shipment = Assert.IsType(result); + Assert.Equal(DateTimeKind.Unspecified, shipment.Sent.Kind); + Assert.Null(shipment.Received); + } + + [Fact] + public void ToolResponseSerializesWithoutClrReflectionObjects() + { + var result = catalog.ExplainMessage("{\"ShipmentId\":1}"); + var json = JsonSerializer.Serialize(result); + using var document = JsonDocument.Parse(json); + Assert.Equal("Matched", document.RootElement.GetProperty("Status").GetString()); + Assert.Equal(1, document.RootElement.GetProperty("Message").GetProperty("ShipmentId").GetInt32()); + } + + [Fact] + public async Task CatalogSupportsConcurrentReaders() + { + var results = await Task.WhenAll(Enumerable.Range(0, 16).Select(_ => Task.Run(() => catalog.ExplainMessage("{\"ShipmentId\":1}")))); + Assert.All(results, result => Assert.Equal(MessageMatchStatus.Matched, result.Status)); + } + + private static MessageCatalog DiscriminatedCatalog() => new(new() + { + DiscriminatorPropertyName = "$type", + DiscriminatorMappings = new Dictionary { ["result"] = "Instruments.Result" } + }); +}