icss 0.1.3 → 0.3.2

data/lib/icss/type/union_schema.rb

@@ -0,0 +1,41 @@
+module Icss
+  module Meta
+
+    #
+    # Describes an Avro Union type.
+    #
+    # Unions are represented using JSON arrays. For example, ["string", "null"]
+    # declares a schema which may be either a string or null.
+    #
+    # Unions may not contain more than one schema with the same type, except for
+    # the named types record, fixed and enum. For example, unions containing two
+    # array types or two map types are not permitted, but two types with different
+    # names are permitted. (Names permit efficient resolution when reading and
+    # writing unions.)
+    #
+    # Unions may not immediately contain other unions.
+    #
+    class UnionSchema
+      #   extend Icss::Meta::ContainerType
+      #   #
+      #   attr_accessor :embedded_types
+      #   attr_accessor :declaration_flavors
+      #   #
+      #   def receive! type_list
+      #     self.declaration_flavors = []
+      #     self.embedded_types = type_list.map do |schema|
+      #       type = TypeFactory.receive(schema)
+      #       declaration_flavors << TypeFactory.classify_schema_declaration(schema)
+      #       type
+      #     end
+      #   end
+      #   def to_schema
+      #     embedded_types.zip(declaration_flavors).map do |t,fl|
+      #       [:structured_schema].include?(fl) ? t.name : t.to_schema
+      #     end
+      #   end
+      # end
+
+    end
+  end
+end

data/lib/icss/view_helper.rb

@@ -1,28 +1,65 @@
 module Icss
-  Message.class_eval do
+  module Meta
+    Message.class_eval do
+
+      def query_string
+        req_fields = request.first.type.fields rescue nil ; return unless req_fields
+        req_fields.map do |field|
+          "#{field.name}=#{first_sample_request_param[field.name.to_s]}"
+        end.join("&")
+      end
+
+      def api_url
+        # all calls accept xml or json
+        "http://api.infochimps.com/#{path}?#{query_string}"
+      end
+
+      def sample_field_value(field)
+        field_name = ((field.respond_to?(:name) && field.name) || field).to_s
+
+        value =  first_sample_request_param[field_name]  # sample value for field
+      end
 
-    def query_string
-      fields = request.first.type.fields     rescue nil ; return unless fields
-      fields.map do |field|
-        "#{field.name}=#{first_sample_request_param[field.name.to_s]}"
-      end.join("&")
     end
 
-    def api_url
-      # all calls accept xml or json
-      "http://api.infochimps.com/#{path}?#{query_string}"
+    RecordField.class_eval do
+      def title
+        return "!!missing!!" if type.blank?
+        # case type
+        # when ArrayType then "array of #{type.title} #{type.to_hash.inspect}"
+        # else type.title
+        # end
+        type.title
+      end
     end
-  end
 
-  RecordField.class_eval do
-    def title
-      return "!!missing!!" if type.blank?
-      # case type
-      # when ArrayType then "array of #{type.title} #{type.to_hash.inspect}"
-      # else type.title
-      # end
-      type.title
+    RecordType.class_eval do
+
+      # * when :display_fields are listed in the :_doc_hints, their field names
+      #   are split on '.' and mapped to the right nested RecordField objects:
+      #   content_location.geo.longitude will give the field for
+      #   content_location in the current type, the geo field in that type, and
+      #   the longitude field object in that type.
+      # * if no :display_fields is given, return the full (flat) set of fields.
+      #
+      def display_fields
+        df_names = self._schema._doc_hints[:display_fields]
+        return fields.map{|f| [f] } if df_names.blank?
+        df_names.map do |fn|
+          name_segs = fn.split('.')
+          type = self
+          sub_fields = []
+          name_segs.map do |name_seg|
+            sub_fields << (type.field_named(name_seg) || name_seg)
+            type = sub_fields.last.type if sub_fields.last.respond_to?(:type)
+            type = type.items if type.respond_to?(:items)
+            type = type.values if type.respond_to?(:values)
+          end
+          sub_fields
+        end
+      end
+
     end
-  end
 
+  end
 end

data/notes/named_array.md

@@ -0,0 +1,32 @@
+### NamedArray type
+
+Defining
+
+```ruby
+  field :slices, NamedArray, :of => AggregateQuantity, :pivoting_on => :name, :receives => :remaining
+```
+
+Lets it equivalently live as
+
+```yaml
+- name: foo
+  average_value: 3
+  slices:
+  - name: subcat_1
+    average_value: 3
+  - name: subcat_2
+    average_value: 3
+```
+
+or naturally pivot to be
+
+```yaml
+foo:
+  average_value: 3
+   subcat_1:
+    average_value: 3
+  subcat_2:
+    average_value: 3
+```
+
+All the rcvr_remaining (unclaimed) properties pivot on their :name field to look like the one or the other at your choice.

data/notes/on_include_vs_extend_etc.rb

@@ -0,0 +1,176 @@
+#!/usr/bin/env ruby
+
+
+
+# klass         Foo                     [:module_self_foo, :module_meth_extif]
+# sgtncl        Foo                     []
+# ---------------
+# obj           ClassIncludingFoo       [:meth_in_class,                          :module_meth_foo, :module_meth_inclif]
+# klass         ClassIncludingFoo       [:meth_in_sgtn_cl,   :self_meth_in_class, --                -- ]
+# sgtncl        ClassIncludingFoo       [:self_meth_sgtn_cl, --                   --                -- ]
+# ---------------
+# obj           ClassExtendingFoo       [:meth_in_class,     --                   --                -- ]
+# klass         ClassExtendingFoo       [:meth_in_sgtn_cl,   :self_meth_in_class, :module_meth_foo, :module_meth_inclif]
+# sgtncl        ClassExtendingFoo       [:self_meth_sgtn_cl, --                   --                -- ]
+# ---------------
+# obj           ClassInclFooInSgtnCl    [:meth_in_class,     --                   --                -- ]
+# klass         ClassInclFooInSgtnCl    [:meth_in_sgtn_cl,   :self_meth_in_class, :module_meth_foo, :module_meth_inclif]
+# sgtncl        ClassInclFooInSgtnCl    [:self_meth_sgtn_cl, --                   --                -- ]
+# ---------------
+# obj           ClassExtFooInSgtnCl     [:meth_in_class,     --                 , --                -- ]
+# klass         ClassExtFooInSgtnCl     [:meth_in_sgtn_cl,   :self_meth_in_class, --                -- ]
+# sgtncl        ClassExtFooInSgtnCl     [:self_meth_sgtn_cl,                      :module_meth_foo, :module_meth_inclif]
+#
+#
+# Ancestor chain
+#
+# klass         Foo                             IncludedInFoo
+# sgtncl        ExtendedInFoo                                           Module  Object  Kernel  BasicObject
+# #
+# klass         ClassExtendingFoo                               SimpleClass     Object  Kernel  BasicObject
+# sgtncl                                Foo     IncludedInFoo   Class   Module  Object  Kernel  BasicObject
+# #
+# klass         ClassIncludingFoo       Foo     IncludedInFoo   SimpleClass     Object  Kernel  BasicObject
+# sgtncl                                                        Class   Module  Object  Kernel  BasicObject
+# #
+# klass         ClassInclFooInSgtnCl                            SimpleClass     Object  Kernel  BasicObject
+# sgtncl                                Foo     IncludedInFoo   Class   Module  Object  Kernel  BasicObject
+# #
+# klass         ClassExtFooInSgtnCl                             SimpleClass     Object  Kernel  BasicObject
+# sgtncl                                                        Class   Module  Object  Kernel  BasicObject
+
+
+# --------------- Foo
+# module_meth_extif                     class   Foo                             Module
+# module_self_foo                       class   Foo                             Module
+#
+# --------------- ClassExtendingFoo
+# meth_in_class                         obj     #<ClassExtendingFoo:0x00000100e ClassExtendingFoo
+# self_meth_in_class                    class   ClassExtendingFoo               Class                           #<Class:ClassExtendingFoo>
+# meth_in_sgtn_cl                       class   ClassExtendingFoo               Class                           #<Class:ClassExtendingFoo>
+# self_meth_sgtn_cl                     sgtn_cl #<Class:ClassExtendingFoo>      Class
+# module_meth_foo                       class   ClassExtendingFoo               Class                           #<Class:ClassExtendingFoo>
+# module_meth_inclif                    class   ClassExtendingFoo               Class                           #<Class:ClassExtendingFoo>
+#
+# --------------- ClassIncludingFoo
+# meth_in_class                         obj     #<ClassIncludingFoo:0x000001020 ClassIncludingFoo
+# self_meth_in_class                    class   ClassIncludingFoo               Class                           #<Class:ClassIncludingFoo>
+# meth_in_sgtn_cl                       class   ClassIncludingFoo               Class                           #<Class:ClassIncludingFoo>
+# self_meth_sgtn_cl                     sgtn_cl #<Class:ClassIncludingFoo>      Class
+# module_meth_foo                       obj     #<ClassIncludingFoo:0x000001020 ClassIncludingFoo
+# module_meth_inclif                    obj     #<ClassIncludingFoo:0x000001020 ClassIncludingFoo
+#
+# --------------- ClassInclFooInSgtnCl
+# meth_in_class                         obj     #<ClassInclFooInSgtnCl:0x000001 ClassInclFooInSgtnCl
+# self_meth_in_class                    class   ClassInclFooInSgtnCl            Class                           #<Class:ClassInclFooInSgtnCl>
+# meth_in_sgtn_cl                       class   ClassInclFooInSgtnCl            Class                           #<Class:ClassInclFooInSgtnCl>
+# self_meth_sgtn_cl                     sgtn_cl #<Class:ClassInclFooInSgtnCl>   Class
+# module_meth_foo                       class   ClassInclFooInSgtnCl            Class                           #<Class:ClassInclFooInSgtnCl>
+# module_meth_inclif                    class   ClassInclFooInSgtnCl            Class                           #<Class:ClassInclFooInSgtnCl>
+#
+# --------------- ClassExtFooInSgtnCl
+# meth_in_class                         obj     #<ClassExtFooInSgtnCl:0x0000010 ClassExtFooInSgtnCl
+# self_meth_in_class                    class   ClassExtFooInSgtnCl             Class                           #<Class:ClassExtFooInSgtnCl>
+# meth_in_sgtn_cl                       class   ClassExtFooInSgtnCl             Class                           #<Class:ClassExtFooInSgtnCl>
+# self_meth_sgtn_cl                     sgtn_cl #<Class:ClassExtFooInSgtnCl>    Class
+# module_meth_foo                       sgtn_cl #<Class:ClassExtFooInSgtnCl>    Class
+# module_meth_inclif                    sgtn_cl #<Class:ClassExtFooInSgtnCl>    Class
+
+def compare_methods(klass_a, klass_b)
+  puts( "%-31s\tobj   \t%s" %  [klass_a.to_s[0..30], (klass_a.new.public_methods - Object.new.public_methods).inspect]) if klass_a.respond_to?(:new)
+  puts( "%-31s\tklass \t%s" %  [klass_a.to_s[0..30], (klass_a.public_methods - klass_b.public_methods).inspect])
+  puts( "%-31s\tsgtncl\t%s" %  [klass_a.to_s[0..30], (klass_a.singleton_class.public_methods - klass_b.singleton_class.public_methods).inspect])
+  puts '---------------'
+end
+
+def show_anc_chain(klass_a)
+  puts ['klass ', klass_a.ancestors                .reject{|kl| kl.name =~ /^(RSpec|PP::ObjectMixin)/ }].join("\t")
+  puts ['sgtncl', klass_a.singleton_class.ancestors.reject{|kl| kl.name =~ /^(RSpec|PP::ObjectMixin)/ }].join("\t")
+end
+
+def show_method_selfness(klass_a)
+  puts "\n", klass_a
+  on = (klass_a.respond_to?(:new) ? { 'obj' => klass_a.new } : {})
+  on['class']   = klass_a
+  on['sgtn_cl'] = klass_a.singleton_class
+  [
+    :meth_in_class,
+    :self_meth_in_class,
+    :meth_in_sgtn_cl,
+    :self_meth_sgtn_cl,
+
+    :explicit_method_extif,
+    :explicit_method_foo,
+    :module_meth_extif,
+    :module_meth_foo,
+    :explicit_method_inclif,
+    :module_meth_inclif,
+    :module_self_extif,
+    :module_self_foo,
+    :module_self_inclif,
+  ].each do |meth|
+    on.each do |kind, obj|
+      next unless obj.respond_to?(meth)
+      puts( "%-31s\t%-7s\t%-31s\t%-31s\t%s" %  [meth, kind, obj.send(meth)].flatten.map{|x| x.to_s[0..30] } )
+    end
+  end
+end
+
+
+class SimpleClass
+  class << self
+    def self.self_meth_sgtn_cl() ; [self, self.class, ((self.is_a?(Class) && self.ancestors.first == self) ? self.singleton_class : nil)] ; end
+    def meth_in_sgtn_cl()        ; [self, self.class, ((self.is_a?(Class) && self.ancestors.first == self) ? self.singleton_class : nil)] ; end
+  end
+  def self.self_meth_in_class()  ; [self, self.class, ((self.is_a?(Class) && self.ancestors.first == self) ? self.singleton_class : nil)] ; end
+  def meth_in_class()            ; [self, self.class, ((self.is_a?(Class) && self.ancestors.first == self) ? self.singleton_class : nil)] ; end
+end
+
+module IncludedInFoo
+  def self.module_self_inclif()  ; [self, self.class, ((self.is_a?(Class) && self.ancestors.first == self) ? self.singleton_class : nil)] ; end
+  def module_meth_inclif()       ; [self, self.class, ((self.is_a?(Class) && self.ancestors.first == self) ? self.singleton_class : nil)] ; end
+end
+
+module ExtendedInFoo
+  def self.module_self_extif()   ; [self, self.class, ((self.is_a?(Class) && self.ancestors.first == self) ? self.singleton_class : nil)] ; end
+  def module_meth_extif()        ; [self, self.class, ((self.is_a?(Class) && self.ancestors.first == self) ? self.singleton_class : nil)] ; end
+end
+
+module Foo
+  include IncludedInFoo
+  extend  ExtendedInFoo
+  def self.module_self_foo()     ; [self, self.class, ((self.is_a?(Class) && self.ancestors.first == self) ? self.singleton_class : nil)] ; end
+  def module_meth_foo()          ; [self, self.class, ((self.is_a?(Class) && self.ancestors.first == self) ? self.singleton_class : nil)] ; end
+end
+
+class ClassExtendingFoo < SimpleClass
+  extend Foo
+  class << self
+  end
+end
+
+class ClassIncludingFoo < SimpleClass
+  include Foo
+  class << self
+  end
+end
+
+class ClassInclFooInSgtnCl < SimpleClass
+  class << self
+    include Foo
+  end
+end
+
+class ClassExtFooInSgtnCl < SimpleClass
+  class << self
+    extend Foo
+  end
+end
+
+[Foo,
+  ClassExtendingFoo, ClassIncludingFoo, ClassInclFooInSgtnCl,
+  ClassExtFooInSgtnCl,
+].each do |kl|
+  show_method_selfness(kl)
+  compare_methods(kl ,  Class)
+end

data/notes/technical_details.md

@@ -0,0 +1,278 @@
+
+#### Types, Properties and Individuals
+
+There are things in the world that we know as "restaurants" -- for example, in
+Austin you can't to better than "Torchy's Tacos". It, like all restaurants, have
+some notion of a "name" and a "menu".
+
+* "Restaurant" is a _*type*_: a group sharing common properties.
+* "Torchy's Tacos" is an _*individual*_.
+* "name" and "menu" are _*properties*_ of a type.
+* An individual has _*values*_ for those properties: the restaurant "Torchy's
+  Taco's" has a menu which includes the "Dirty Sanchez" (no, really.)
+
+In ruby, we might represent this as follows (greatly simplified):
+
+```ruby
+    class Restaurant
+      field :name, String
+      field :menu, Array, :items => String
+      field :geo,  GeoCoordinates
+    end
+    yum = Restaurant.receive({
+      :name => "Torchy's Taco's",
+      :menu => ["Dirty Sanchez", "Fried Avocado"] ,
+      :geo  => { :longitude => 30.295, :latitude => -97.745 },
+      })
+    yum.name          # "Torchy's Taco's"
+    yum.geo.latitude  # -97.745
+```
+
+* The _type_ is implemented with the *class* `Restaurant`.
+* Its _properties_ are described as `field`s, each with its own type.
+* An _individual_ is represented by an *instance* of that class.
+
+Probably most of this was boring and/or familiar. To clear the rest of the
+straightforward stuff out of the way,
+
+* A "Restaurant" is a specialization of a "Place": it has a "geo" property, just
+  as "Bowling Alley" and "Mountain" do. We'll represent that as straightforward
+  inheritance: `Restaurant` is a subclass of `Place`.
+* A "Place" is itself a specialization of "Tangible Things", for which we will
+  use the ruby class `Thing`.
+* A "Restaurant" is actually also a "Business", itself also a specialization of
+  "Thing".  Using a trick you'll hear more about below, we can actually handle
+  this easily using module inclusion (`include`).
+
+So this gives us (still simplified, but less so):
+
+```ruby
+    class Thing
+      field :name, String
+    end
+
+    class Place < Thing
+      field :geo,  GeoCoordinates
+    end
+
+    class Business < Thing
+      field :opening_hours, Duration
+    end
+
+    class Restaurant < Place
+      include Meta::BusinessType
+      field :menu, Array, :items => String
+    end
+
+    class Mountain < Place
+      field :height_of_peak, Integer, :doc => "In meters"
+    end
+
+    yum = Restaurant.receive({
+      :name => "Torchy's Taco's",
+      :menu => ["Dirty Sanchez", "Fried Avocado"] ,
+      :geo  => { :longitude => 30.295, :latitude => -97.745 },
+      })
+    yum.name          # "Torchy's Taco's"
+    yum.geo.latitude  # -97.745
+```
+
+### RecordModel
+
+Including `Icss::Meta::RecordModel` gives you these superpowers:
+
+* `.field` -- create accessors and receivers for a property
+* `.fields` and `.field_names` -- describe the fields. (field names is guaranteed in order.)
+* `.receive` -- create an instance given a (nested) hash of values; calls
+  in turn `.receive` on each field's type.
+
+The class and instance behavior of `Place` (a direct child class of `Thing`) is
+effectively (apart from one important detail) as follows:
+
+    Behavior        Model               Instance Methods        Type                    Class Methods              
+    --------------  -----------------   -----------------       ---------------------   ------------------------   
+    (superclasses)  Object              ...many...                                      ...many...
+    structure type:                                             Meta::BaseType          .metamodel,.to_schema
+                    Meta::RecordModel   #receive!               Meta::RecordType        .receive, .field, .fields
+    parent models:  Thing               #name,#receive_name,&c
+    model klass:    Place               #geo, #receive_geo,&c
+
+Note carefully the following relationships:
+    
+      torchys = Place.new({...})
+
+      # true:
+      torchys.is_a? Thing
+      torchys.is_a? Meta::RecordModel 
+      torchys.is_a? Object
+
+      # not true:
+      torchys.is_a? Meta::RecordType
+      
+      # true:
+      Place     < Thing
+      Place     < Meta::RecordModel
+      Place.is_a? Meta::RecordType
+
+### metamodel
+
+Here's the important detail promised earlier about inheritance. We actually slip
+in a little overlay module, the `metamodel`:
+
+    Behavior        Model               Instance Methods        Type                    Class Methods              
+    --------------  -----------------   -----------------       ---------------------   ------------------------   
+    (superclasses)  Object              ...many...                                      ...many...
+    structure type:                                             Meta::BaseType          .metamodel,.to_schema
+                    Meta::RecordModel   #receive!               Meta::RecordType        .receive, .field, .fields
+    parent models:  Meta::ThingModel    #name,#receive_name,&c
+                    Thing               
+    metamodel:      Meta::PlaceModel    #geo, #receive_geo,&c
+    model klass:    Place                        <--- call super, override things, go crazy --->
+
+This lets us (a) enable multiple inheritance, and (b) let a class declare a
+field but only override *some* of its behavior (i.e. still letting you use
+`super`).
+
+We scribble all the instance methods for a place onto the `Meta::PlaceModel`
+*module*. When the `Place` class calls `include Meta::PlaceModel`, it acquires
+the prescribed behavior, but can override as required.  Furthermore, any other
+class can accomplish "Placehood" by *also* `include`ing the `Meta::PlaceModel`
+metamodel. 
+
+The infochimps API uses this to good effect, where data sets often introduce
+behavior across an entire universe of otherwise distinct types. Objects from
+Twitter would generically be represented as `Social::Person` (an account),
+`Event::UserTweets` (messages), and subclasses of `Geo::Place` (place checkins).
+All have implied geolocations, and could naturally coexist on a map. Other data
+sources imply other attributes: not just foursquare and yelp but also news
+articles and stock filings.  We can inject Twitter geolocation information
+without subclassing everything in sight
+(`RestaurantOnTwitterThatIsAlsoABranchOfAPubliclyTradedCompany`) or requiring
+the prolix madness of an RDF graph
+(`<http://ding.us/not/actually/a/url/torchys_tacos>
+<http://some.rand.om/ontology#hasPropertyYouCantRememberSpellingOf>
+34^^<http://with.com/value/that/is/twelve/miles/long/even/though/its/a/goddamn/integer>`)
+
+### Model vs Type vs Schema
+
+Now we want a way to programmatically describe and generate types. If we're not
+careful, we'll end up going mad discussing how to type up the typical type of
+type `Type` properly having property `schema` of type `RecordSchema`, or (even
+worse) wind up in the omphaloskeptic realm of Semantic Web Ontologies. Eff that
+-- this is called the Infochimps Stupid Schema, precisely to remind you it's
+just a data model, we should really just relax.
+
+However, if you must spend some time to understand how a small amount of clever
+enables that greater and more productive recklessness, a certain measure of
+careful terminology is required.
+
+The regular kind of _type_ we've been discussing is a `Model` -- its individuals
+correspond to things in the real world. A `Thing` is a model, and most things
+are `Thing`s. `Integer` and `IsFriendOf` (a kind of `Relation`) are both models
+but not `Thing`s. Recapping what you know,
+
+  - **instances** of a model represent individuals;
+  - **instance methods** of a model characterize a type's behavior, specifically
+  - **fields**, which represent properties and accept values describing the individual.
+
+We also want to be able to discuss properties and impart shared behavior among
+types themselves. For example,
+
+  - a `Restaurant` place, a `WeatherObservation` statistical summary, and a
+    `IsFriendOf` relation are quite different at the model level -- they
+    represent respectively a tangible Thing, an intangible Thing and a
+    non-Thing. But all of them are structured records, with fields an so on.
+
+  - A `FilePath`, a `RawJsonBlob` and a `Url` are all represented as simple
+    strings, but each has a distinct semantic meaning, and each implies rules
+    that would allow a computer to validate an instance's contents look right.
+    
+  - We of course use `Array` to hold collections of items, and `Hash` to hold
+    labelled collections of items. Wherever possible, we'd like to specify
+    "Array of MusicAlbum" and so forth.
+
+Let us now introduce the `Schema`, which characterizes commonalities among `Model` types. 
+
+
+    <"Torchy's" instance>    manufactured by Restaurant
+    <"Torchy's">.menu()      instance methods from Restaurant
+    
+                             <Restaurant class>                 described by RecordSchema
+                             <Restaurant>.field_names           class methods from RecordSchema
+
+A person who find this sort of thing elegant might point out that the
+properties of a Schema describe specifics of a model; given values
+characterizing those specifics, the Schema manufactures an individual
+Model. That is: a Schema is a type for individual Types.
+
+But if you're like me you're better off just remembering 
+
+> Schema == classes and class methods for a type;
+> Model  == instances and instance methods for a type.
+
+In implementation land, a Schema is a class, with a distinct existence from its
+type. If you're working with types on their own, you want schema objects; 
+
+(In fact, you may discover to your horror that a Schema is itself a RecordType:
+it's turtles all the way down.)
+
+### Structured Schema (Array, Map, Enum, Fixed)
+
+#### Meta::ArraySchema
+
+The schema prescribes the *class* of items the `Array` should hold: for example,
+an album's `tracks` property is an array of `MusicRecordings`.
+
+    Behavior        Model               Instance Methods        Type                    Class Methods              
+    --------------  -----------------   -----------------       ---------------------   ------------------------   
+    (superclasses)  Object,Array        ...many...                                      ...many...
+    structure type:                                             Meta::BaseType          .metamodel,.to_schema
+                                                                Meta::ArrayType         .receive
+    metamodel:      --                                          
+    model klass:    ArrayOfInt                                  (directly on class)     .items
+    
+    Schema: class Meta::ArraySchema
+
+For a record model, an individual schema typically doesn't have much to say
+about the model class itself. Since models are usually real-world objects we'd
+like to handle generically, we focus our interest on fields and instance
+methods. An `Array` is something whose *individuals* should be completely
+generic: we care about all the interesting things in a list, not the bag that
+holds them. The schema for an array (as well as for Hash, Fixed and Enum)
+prescribes information about the *type* not the *model*
+
+Now after I just sold you on the virtues of a metamodel in the case of a record,
+you might expect an analogous module to extend the class. There's no practical
+benefit or need for this, though, so we currently just scribble the .items class
+method directly onto the class.
+
+#### Meta::HashSchema
+
+    Behavior        Model               Instance Methods        Type                  Class Methods              
+    --------------  -----------------   -----------------       ---------------------   ------------------------   
+    (superclasses)  Object,Hash         ...many...                                      ...many...
+    structure type:                                             Meta::BaseType          .metamodel,.to_schema
+                                                                Meta::HashType          .receive
+    metamodel:      --                                          
+    model klass:    HashOfYourMom                               (directly on class)     .values  
+
+#### Meta::FixedSchema
+
+    Behavior        Model               Instance Methods        Type                    Class Methods              
+    --------------  -----------------   -----------------       ---------------------   ------------------------   
+    (superclasses)  Object,String       ...many...                                      ...many...
+    structure type:                                             Meta::BaseType          .metamodel,.to_schema
+                                                                Meta::FixedType         .receive
+    metamodel:      --                                          
+    model klass:    Fixed16                                     (directly on class)     .bytesize
+
+#### Meta::EnumSchema
+
+    Behavior        Model               Instance Methods        Type                  Class Methods              
+    --------------  -----------------   -----------------       ---------------------   ------------------------   
+    (superclasses)  Object,String       ...many...                                      ...many...
+    structure type:                                             Meta::BaseType          .metamodel,.to_schema
+                                                                Meta::EnumType          .receive
+    metamodel:      --                                          
+    model klass:    CountryCode                                 (directly on class)     .symbols 
+