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" }
+ });
+}