Apply suggestions from code review

Co-authored-by: Oscar Esteban <[email protected]>

Author: effigies

src/schema/meta/context.yaml

@@ -407,7 +407,7 @@ properties:
         type: integer
       axis_codes:
         name: 'axis codes'
-        description: 'Orientation labels indicating primary direction of data axes.'
+        description: 'Orientation labels indicating primary direction of data axes defined with respect to the object of interest.'
         type: array
         minItems: 3
         maxItems: 3

src/schema/objects/entities.yaml

@@ -84,11 +84,16 @@ direction:
     Therefore, if the `dir-<label>` entity is present in a filename,
     `"PhaseEncodingDirection"` MUST be defined in the associated metadata.
 
-    Labels need not follow any particular convention,
-    and JSON metadata MUST take precedence in interpreting an image.
-    Generic labels, such as `dir-reference` and `dir-reversed` avoid any possible inconsistency.
-    `dir-j0` and `dir-j1` can indicate `"PhaseEncodingDirection": "j"` and `"j-"` (or vice versa),
+    Labels need not follow any particular convention and in case of conflict,
+    JSON metadata MUST take precedence in interpreting an image.
+
+    For example, `dir-j0` and `dir-j1` can indicate `"PhaseEncodingDirection": "j"` and `"j-"` (or vice versa),
     identifying the phase-encoding axis while avoiding indicating polarity.
+    However, in case of a dataset indicating `dir-j0` with `"PhaseEncodingDirection": "i"`, the
+    JSON metadata overrides the entity `dir-` setting.
+
+    The use of generic labels, such as `dir-reference` and `dir-reversed`, is RECOMMENDED
+    to avoid any possible inconsistency.
 
     To avoid inconsistency, if the `<label>` is `AP`, `PA`, `LR`, `RL`, `SI`, or `IS`,
     then the `"PhaseEncodingDirection"` SHOULD correspond to the data