Skip to content

Commit 9bfd75f

Browse files
authored
Add asset validation docs page (#163)
1 parent eb6fd19 commit 9bfd75f

6 files changed

Lines changed: 160 additions & 5 deletions

File tree

‎docs/architecture/apps-and-consoles.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 3
2+
sidebar_position: 6
33
---
44

55
# Apps and consoles

‎docs/architecture/asset-location-tracking.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 4
2+
sidebar_position: 5
33
---
44

55
# Asset location tracking
Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
---
2+
sidebar_position: 4
3+
---
4+
5+
# Asset Validation
6+
7+
This document summarises how asset validation is performed and how it relates to the asset type model.
8+
9+
## AssetTypeInfo Model Structure
10+
11+
```mermaid
12+
classDiagram
13+
direction TB
14+
15+
class AssetTypeInfo {
16+
+AssetDescriptor~?~ assetDescriptor
17+
+Map attributeDescriptors
18+
+MetaItemDescriptor~?~[] metaItemDescriptors
19+
+ValueDescriptor~?~[] valueDescriptors
20+
}
21+
note for AssetTypeInfo "Source: AssetTypeInfo.java"
22+
23+
class AssetDescriptor~T~ {
24+
+String name
25+
+Class~T~ type
26+
+String icon
27+
+String color
28+
}
29+
note for AssetDescriptor "Agent subtype: AgentDescriptor"
30+
31+
class AttributeDescriptor~T~ {
32+
+String name [Inherited]
33+
+ValueDescriptor type [Inherited]
34+
+ValueConstraint constraints [Inherited]
35+
+ValueFormat format [Inherited]
36+
+String[] units [Inherited]
37+
+MetaMap meta [Own]
38+
+Boolean optional [Own]
39+
}
40+
note for AttributeDescriptor "Extends AbstractNameValueDescriptor, Holder~T~"
41+
42+
class ValueDescriptor {
43+
+String name
44+
+Class~T~ type
45+
+constraints[]
46+
+arrayDimensions
47+
+jsonType
48+
}
49+
50+
class MetaMap {
51+
+ValueConstraint[] CONSTRAINTS
52+
}
53+
note for MetaMap "Attribute-level meta items\nKeyed by name"
54+
55+
class ValueConstraint {
56+
<<abstract>>
57+
+evaluate()
58+
+message
59+
+getParams()
60+
}
61+
62+
class ConcreteSubtypes {
63+
Size, Min, Max, Pattern, AllowedValues
64+
Past, PastOrPresent, Future, FutureOrPresent
65+
NotEmpty, NotBlank, NotNull
66+
}
67+
note for ConcreteSubtypes "Discriminated by 'type' field"
68+
69+
%% Relationships & Structural Dependencies
70+
AssetTypeInfo --> AssetDescriptor~T~ : assetDescriptor
71+
AssetTypeInfo --> AttributeDescriptor~T~ : attributeDescriptors
72+
AttributeDescriptor~T~ --> ValueDescriptor : type
73+
AttributeDescriptor~T~ --> MetaMap : meta
74+
AttributeDescriptor~T~ --> ValueConstraint : constraints
75+
MetaMap --> ValueConstraint : holds via MetaItemType
76+
ValueConstraint <|-- ConcreteSubtypes : dynamic subtypes
77+
```
78+
---
79+
80+
## Constraint Validation Logic in ValueUtil.validateValue()
81+
82+
There are four independent sources of constraints, all evaluated cumulatively. A value is valid only if it passes every constraint from every source.
83+
84+
```
85+
ValueUtil.validateValue(
86+
attributeDescriptor, // static descriptor (from AssetTypeInfo)
87+
valueDescriptor, // the value's type descriptor
88+
metaHolder, // the live attribute instance (has its own MetaMap)
89+
now, context, value
90+
)
91+
│
92+
├─── [1] ValueDescriptor.constraints[] ← constraints on the VALUE TYPE itself
93+
│ e.g. ValueType.NUMBER might have Min(0)
94+
│ validateConstraints(arrayDimensions, constraints, ...)
95+
│
96+
├─── [2] AttributeDescriptor.constraints[] ← constraints on the ATTRIBUTE DESCRIPTOR
97+
│ e.g. a specific attribute defined with .withConstraints(new Max(100))
98+
│ validateConstraints(arrayDimensions, constraints, ...)
99+
│
100+
├─── [3] AttributeDescriptor.meta ← CONSTRAINTS meta on the DESCRIPTOR
101+
│ attributeDescriptor.getMeta()
102+
│ .get(MetaItemType.CONSTRAINTS) // MetaItemDescriptor<ValueConstraint[]>
103+
│ .flatMap(ValueHolder::getValue) // Optional<ValueConstraint[]>
104+
│ Each constraint → validateValueConstraint(...)
105+
│
106+
└─── [4] metaHolder.getMeta() ← CONSTRAINTS meta on the LIVE ATTRIBUTE
107+
(the attribute instance itself, not the descriptor)
108+
.get(MetaItemType.CONSTRAINTS)
109+
Each constraint → validateValueConstraint(...)
110+
```
111+
112+
## Array value recursion (validateConstraints)
113+
114+
```java
115+
// ValueUtil.java:1043
116+
private static boolean validateConstraints(Integer dimensions, ValueConstraint[] constraints, ..., Object value) {
117+
if (dimensions == null || dimensions == 0 || value == null) {
118+
// Leaf: evaluate each constraint directly against the value
119+
return Arrays.stream(constraints)
120+
.anyMatch(c -> !validateValueConstraint(..., c, value));
121+
} else {
122+
// Array: recurse into each element, decrementing dimension count
123+
return Arrays.stream((Object[]) value)
124+
.anyMatch(v -> validateConstraints(dimensions - 1, constraints, ..., v));
125+
}
126+
}
127+
```
128+
129+
When valueDescriptor.arrayDimensions > 0, constraints are applied to each element, not the array itself (dimension is decremented on each recursion). Paths for error reporting are not updated during recursion, so violations always point to the attribute root.
130+
131+
## `validateValueConstraint` (the leaf evaluator)
132+
133+
```java
134+
// ValueUtil.java:1051
135+
public static boolean validateValueConstraint(..., ValueConstraint valueConstraint, Object value) {
136+
if (!valueConstraint.evaluate(value, now)) {
137+
// 1. Inject message parameters (min/max/pattern/etc.) into Hibernate context
138+
// 2. Build violation with constraint's message template key
139+
// 3. Apply the path provider to set the property path
140+
return false; // invalid
141+
}
142+
return true; // valid
143+
}
144+
```
145+
146+
## Constraint source summary
147+
148+
| Source | Where defined | Applied via |
149+
|-----------------------------------------|--------------|-------------|
150+
| ValueDescriptor.constraints\[\] | On the value type (e.g. ValueType.NUMBER) | validateConstraints() with array recursion |
151+
| AttributeDescriptor.constraints\[\] | On the static attribute definition | validateConstraints() with array recursion |
152+
| AttributeDescriptor.meta\[CONSTRAINTS\] | In the descriptor's MetaMap, key "constraints" | Direct per-constraint loop |
153+
| metaHolder.meta\[CONSTRAINTS\] | On the live Attribute instance's MetaMap | Direct per-constraint loop |
154+
155+
The key distinction between sources 3 and 4 is that source 3 comes from the static descriptor (set by the developer defining the asset model), while source 4 comes from the live attribute (set at runtime, e.g. by a user configuring constraints via the UI or API). Both are checked with MetaItemType.CONSTRAINTS — the same MetaItemDescriptor\<ValueConstraint\[\]\>.

‎docs/architecture/esp32-device.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 5
2+
sidebar_position: 7
33
---
44

55
# ESP32 devices

‎docs/architecture/manager-endpoints-and-file-paths.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 1
2+
sidebar_position: 2
33
---
44

55
# Manager endpoints and file paths

‎docs/architecture/security.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 2
2+
sidebar_position: 3
33
---
44

55
# Security

0 commit comments

Comments
 (0)