Fix "Unknown parent" problem. Improve constraint presentation. Add de…

…precated markers. (#126)

* Fix "Unknown parent" problem in references which occured for extensions that patch classes and add attributes. 

* Improve presentation of constraint, improving wording and adding footnote links after requirements; issue #125.

* Add deprecated marker after class and object names on main page as well as references lists; issue #121.

* Remove the example wording in observables note at top of many pages (the example doesn't always apply, so is needlessly confusing).

lib/schema/cache.ex

@@ -39,12 +39,6 @@ defmodule Schema.Cache do
   @type object_t() :: map()
   @type category_t() :: map()
   @type dictionary_t() :: map()
-  @type link_t() :: %{
-          group: :common | :class | :object,
-          type: String.t(),
-          caption: String.t(),
-          attribute_keys: nil | MapSet.t(String.t())
-        }
 
   @doc """
   Load the schema files and initialize the cache.

lib/schema/profiles.ex

@@ -68,7 +68,7 @@ defmodule Schema.Profiles do
           acc
 
         profile ->
-          link = %{group: group, type: Atom.to_string(item_name), caption: item[:caption]}
+          link = Schema.Utils.make_link(group, item_name, item)
           profile = Map.update(profile, :_links, [link], fn links -> [link | links] end)
           Map.put(acc, p, profile)
       end

lib/schema/utils.ex

@@ -11,6 +11,14 @@ defmodule Schema.Utils do
   @moduledoc """
   Defines map helper functions.
   """
+  @type link_t() :: %{
+          :group => :common | :class | :object,
+          :type => String.t(),
+          :caption => String.t(),
+          optional(:deprecated?) => boolean(),
+          optional(:attribute_keys) => nil | MapSet.t(String.t())
+        }
+
   require Logger
 
   @spec to_uid(binary() | atom()) :: atom
@@ -199,10 +207,24 @@ defmodule Schema.Utils do
     end
   end
 
+  @spec make_link(:common | :class | :object, atom() | String.t(), map()) :: link_t()
+  def make_link(group, type, item) do
+    if Map.has_key?(item, :"@deprecated") do
+      %{
+        group: group,
+        type: to_string(type),
+        caption: item[:caption] || "*No name*",
+        deprecated?: true
+      }
+    else
+      %{group: group, type: to_string(type), caption: item[:caption] || "*No name*"}
+    end
+  end
+
   # Adds attribute's used-by links to the dictionary.
   defp add_common_links(dict, class) do
     Map.update!(dict, :attributes, fn attributes ->
-      link = %{group: :common, type: class[:name], caption: class[:caption]}
+      link = make_link(:common, class[:name], class)
 
       update_attributes(
         class,
@@ -218,10 +240,10 @@ defmodule Schema.Utils do
       type =
         case class[:name] do
           nil -> "base_event"
-          _ -> Atom.to_string(class_key)
+          _ -> class_key
         end
 
-      link = %{group: :class, type: type, caption: class[:caption] || "*No name*"}
+      link = make_link(:class, type, class)
 
       update_attributes(
         class,
@@ -240,12 +262,7 @@ defmodule Schema.Utils do
 
   defp add_object_links(dictionary, {object_key, object}) do
     Map.update!(dictionary, :attributes, fn dictionary_attributes ->
-      link = %{
-        group: :object,
-        type: Atom.to_string(object_key),
-        caption: object[:caption] || "*No name*"
-      }
-
+      link = make_link(:object, object_key, object)
       update_attributes(object, dictionary_attributes, link, &update_object_links/2)
     end)
   end

lib/schema_web/templates/page/class.html.eex

@@ -20,6 +20,7 @@ limitations under the License.
 <% extension = @data[:extension] %>
 <% observables = @data[:observables] %>
 <% references = @data[:references] %>
+<% constraints = @data[:constraints] %>
 
 <div class="row">
   <div class="col-md move-up">
@@ -41,8 +42,7 @@ limitations under the License.
       <%= raw description(@data) %>
     </div>
     <div class="text-secondary mt-2">
-      <strong>Note:</strong> a superscript &quot;O&quot; after a caption indicates attribute is an observable,
-      for example: <strong>Device <sup>O</sup></strong>.
+      <strong>Note:</strong> a superscript &quot;O&quot; after a caption indicates attribute is an observable.
       <%= if observables != nil and !Enum.empty?(observables) do %>Class-specific attribute path observables
       are <a href="#observables">at the bottom of this page</a>.<% end %>
     </div>
@@ -108,7 +108,7 @@ limitations under the License.
           <td class="name"><%= raw format_attribute_caption(@conn, key, field) %></td>
           <td data-toggle="tooltip" title="<%= format_class_attribute_source(@data[:key], field) %>"><%= raw format_attribute_name(key) %></td>
           <td class="capitalize"><%= field[:group] %></td>
-          <td class="capitalize"><%= format_requirement(field) %></td>
+          <td><%= raw format_requirement(constraints, key, field) %></td>
           <td class="extensions"><%= raw format_type(@conn, field) %></td>
           <td><%= raw format_desc(key, field) %></td>
         </tr>
@@ -117,7 +117,6 @@ limitations under the License.
   </table>
 </div>
 
-<% constraints = @data[:constraints] %>
 <%= if constraints != nil and map_size(constraints) > 0 do %>
   <h5>Constraints</h5>
   <div>

lib/schema_web/templates/page/data_types.html.eex

@@ -18,7 +18,7 @@ limitations under the License.
       <%= raw @data[:description] %>
     </div>
     <div class="text-secondary mt-2">
-      <strong>Note:</strong> a superscript &quot;O&quot; after a caption indicates type is an observable, for example: <strong>Hostname <sup>O</sup></strong>.
+      <strong>Note:</strong> a superscript &quot;O&quot; after a caption indicates type is an observable.
     </div>
   </div>
 </div>

lib/schema_web/templates/page/dictionary.html.eex

@@ -17,8 +17,7 @@ limitations under the License.
       <%= raw @data[:description] %>
     </div>
     <div class="text-secondary mt-2">
-      <strong>Note:</strong> a superscript &quot;O&quot; after a caption indicates attribute is an observable,
-      for example: <strong>Device <sup>O</sup></strong>.
+      <strong>Note:</strong> a superscript &quot;O&quot; after a caption indicates attribute is an observable.
       (Class-specific and object-specific attribute observables are <em>not</em> shown on this page.)
     </div>
   </div>

lib/schema_web/templates/page/index.html.eex

@@ -55,7 +55,7 @@ limitations under the License.
               <% path = Routes.static_path(@conn, "/classes/" <> name) %>
               <tr class="ocsf-class" <%= raw format_profiles(class[:profiles])%>>
                 <td class='align-middle" style="height: 36px; overflow:auto;'>
-                  <a href='<%= path %>'><%= raw format_caption(name, class) %></a>
+                  <%= raw format_linked_class_caption(path, name, class) %>
                 </td>
               </tr>
             <% end %>

lib/schema_web/templates/page/object.html.eex

@@ -15,6 +15,7 @@
 </script>
 
 <% references = @data[:references] %>
+<% constraints = @data[:constraints] %>
 
 <div class="row">
   <div class="col-md move-up">
@@ -44,8 +45,7 @@
       <%= raw description(@data) %>
     </div>
     <div class="text-secondary mt-2">
-      <strong>Note:</strong> a superscript &quot;O&quot; after a caption indicates attribute is an observable,
-      for example: <strong>Device <sup>O</sup></strong>.
+      <strong>Note:</strong> a superscript &quot;O&quot; after a caption indicates attribute is an observable.
     </div>
     <%= if references != nil and !Enum.empty?(references) do %>
     <dd>
@@ -98,7 +98,7 @@
       <tr class="<%= field_classes(field)%>">
         <td class="name"><%= raw format_attribute_caption(@conn, key, field) %></td>
         <td data-toggle="tooltip" title="<%= format_object_attribute_source(@data[:key], field) %>"><%= raw format_attribute_name(key) %></td>
-        <td class="capitalize"><%= format_requirement(field) %></td>
+        <td><%= raw format_requirement(constraints, key, field) %></td>
         <td class="extensions"><%= raw format_type(@conn, field) %></td>
         <td><%= raw format_desc(key, field) %></td>
       </tr>
@@ -116,7 +116,6 @@
     <%= raw object_links(@conn, @data[:name], links) %>
   </div>
 <% end %>
-<% constraints = @data[:constraints] %>
 <%= if constraints != nil and map_size(constraints) > 0 do %>
   <h5 class="mt-3">Constraints</h5>
   <div>

lib/schema_web/templates/page/objects.html.eex

@@ -16,7 +16,7 @@ limitations under the License.
       The OCSF objects. An object is a complex data type, which is a collection of other attributes. Some objects represent entities or artifacts, but not all.
     </div>
     <div class="text-secondary mt-2">
-      <strong>Note:</strong> a superscript &quot;O&quot; after a caption indicates object is an observable, for example: <strong>File <sup>O</sup></strong>.
+      <strong>Note:</strong> a superscript &quot;O&quot; after a caption indicates object is an observable.
     </div>
   </div>
   <div class="col-md-auto fixed-right mt-2">

lib/schema_web/templates/page/profile.html.eex

@@ -23,7 +23,7 @@
       <%= raw @data[:description] %>
     </div>
     <div class="text-secondary mt-2">
-      <strong>Note:</strong> a superscript &quot;O&quot; after a caption indicates attribute is an observable, for example: <strong>Device <sup>O</sup></strong>.
+      <strong>Note:</strong> a superscript &quot;O&quot; after a caption indicates attribute is an observable.
     </div>
   </div>
   <div class="col-md-auto fixed-right mt-2">
@@ -78,7 +78,7 @@
         <td class="name"><%= raw format_attribute_caption(@conn, key, field) %></td>
         <td data-toggle="tooltip" title="<%= field[:_source] %>"><%= key %></td>
         <td class="capitalize"><%= field[:group] %></td>
-        <td class="capitalize"><%= format_requirement(field) %></td>
+        <td><%= raw format_requirement(nil, key, field) %></td>
         <td><%= raw format_type(@conn, field) %></td>
         <td><%= raw format_desc(key, field) %></td>
       </tr>