// // DeadEnds.proto // // Created by Thomas Wetmore on 9/4/2011. // Last changed on 9/6/2011. // Copyright 2011 DeadEnds Software. All rights reserved. // //======== UUIDS =================================================================================== // UUID's are 128-bit values. They are normally represented externally as character strings. Each // DeadEnds record is identified by a UUID. //-------------------------------------------------------------------------------------------------- message UUIDValue { required int64 low = 1; required int64 high = 2; } //======== DATES =================================================================================== // Calendar types. //-------------------------------------------------------------------------------------------------- enum CalendarType { Julian = 1; Gregorian = 2; // ... More ... } // Date types. //-------------------------------------------------------------------------------------------------- enum DateType { Exact = 1; About = 2; Possibly = 3; Probably = 4; Before = 5; After = 6; OnOrBefore = 7; OnOrAfter = 8; Between = 9; // Uses two single date structures. FromTo = 10; // Uses two single date structures. Computed = 11; Interpreted = 12; } // Structure representing a single day in a calendar. //-------------------------------------------------------------------------------------------------- message SingleDateStructure { optional CalendarType calendar = 1; // The calender this date is from. optional int32 day = 2; optional int32 month = 3; optional int32 year = 4; // ... More ... ? } // A date structure is a date type, and one or two single date structures. The start date is used // for all date types, and the end date is used only for Between and FromTo dates. //-------------------------------------------------------------------------------------------------- message DateStructure { required DateType type = 1; // The type of this date. optional SingleDateStructure startDate = 2; // The date or the start date. optional SingleDateStructure endDate = 3; // The end date, if any. } //======== PLACES ================================================================================== // Places can be represented as both place structures within events and by specific place records. // Place records represent a place, and can contain sub-places, and at the same time me a part of // more encompassing places. enum PlaceType { Village = 1; Ward = 20; District = 21; Town = 2; City = 3; Parish = 4; County = 5; State = 6; Province = 7; Region = 8; Country = 9; Continent = 10; Planet = 11; StellarSystem = 12; Galaxy = 13; Universe = 14; // In case the multi-universe conjecture of quantum theory proves true. // ... More ... ? } // Place structures can be used in event in lieu of references to place records. //-------------------------------------------------------------------------------------------------- message PlaceStructure { required string name = 2; // Comma-separated string that is the name of this place. optional PlaceType type = 3; // Type of the last component of the name string. repeated UUIDValue parentIds = 4; // Referenes to places this part is a part of. repeated AttributeStructure attributes = 9; optional InfoStructure info = 10; } // Places can also be represented as separate records. //-------------------------------------------------------------------------------------------------- message PlaceMessage { required UUIDValue recordId = 1; // Record id of this place. required PlaceStructure place = 2; // Structure describing this place. } //======== INFO ==================================================================================== // Info structures can appear in any record and can be associated with any attribute within the // records. The structure is defined simply to avoid repeating the same information in numerous // locations throughout. These structures allow media records, sources and notes to be associated // with just about anything. //-------------------------------------------------------------------------------------------------- message InfoStructure { repeated UUIDValue mediaIds = 11; // References to media records. repeated SourceStructure sources = 12; // Local source structures. repeated UUIDValue sourceIds = 13; // References to source records. repeated string notes = 14; // Local notes. repeated UUIDValue noteIds = 15; // References to shared notes. } //======== ATTRIBUTES ============================================================================== // Attributes allow any kind of information to be recorded about any record and most structures // within records. Attributes are recursive and can be structured to any depth. Attributes may // refer to media records, and may have sources or notes. A number of key strings have been defined // to carry special meaning in certain contexts. An attribute is a key/value pair that can be // structured to any depth with sub-attributes. Dates can be associated with attributes if the // attributes have a time component to them (e.g., having a specific rank in the military). //-------------------------------------------------------------------------------------------------- message AttributeStructure { required string key = 1; // The key or name of this attribute. optional string valu = 2; // The value of this attribute; optional because the value may be // deeper down in sub-attributes. optional string text = 3; // Optional transcribed form of the attribute's value. repeated AttributeStructure attributes = 4; // Sub-attributes of this attribute. optional InfoStructure info = 10; repeated DateStructure dates = 16; // Attributes may have dates. }; //======== SOURCES ================================================================================= // Source structures allow source information to be kept as structures within records instead of as // separate records. However, a source structure may refer to source records that are further up // the source chain. Sources have a containment hierarchy where each source may be contained in any // number of higher level sources. // // The attributes of the source structures and source records should generally conform to some // established set of templates for standard citations. //-------------------------------------------------------------------------------------------------- // Types of sources. //-------------------------------------------------------------------------------------------------- enum SourceType { Book = 1; Letter = 2; BirthRecord = 3; MarriageRecord = 4; DeathRecord = 5; BaptismRecord = 6; BurialRecord = 7; LandRecord = 8; MilitaryRecord = 9; CensusRecord = 10; NaturalizationRecord = 11; ArrivalRecord = 12; Conclusion = 20; } // Source structures are used in records and justify the record or record component they apply to. //-------------------------------------------------------------------------------------------------- message SourceStructure { required SourceType type = 2; // Type of source. optional string description = 3; // Description of source. repeated AttributeStructure attributes = 9; // The attributes of this source structure. optional InfoStructure info = 10; // Any associated information about this source. } // Source records can exist in multiple hierarchies, allowing the user to break down the source // universe into any number of levels and using any standard templates they so desire. //-------------------------------------------------------------------------------------------------- message SourceMessage { required UUIDValue recordId = 1; // The id of this source record. required SourceStructure source = 2; // The structure with the source. } //======== RELATIONS =============================================================================== // Relation types are used for relationships between persons and roles between events and persons. //-------------------------------------------------------------------------------------------------- enum RelationType { Parent = 1; Child = 2; Sibling = 3; Cousin = 4; Uncle = 5; Aunt = 6; GrandParent = 7; GrandChild = 8; Friend = 9; Neighbor = 10; Judge = 11; Clerk = 12; } // Relation subtypes are used to qualify relation types when possible or necessary. //-------------------------------------------------------------------------------------------------- enum RelationSubtype { Natural = 1; Step = 2; Half = 3; InLaw = 4; Adoptive = 5; Foster = 6; Unknown = 7; } // TODO: need to handle cousins, uncles, aunts and multi-great grand parents/children better. // Relation structures are used in person records to refer to other persons that have a // a relationship with this person. //-------------------------------------------------------------------------------------------------- message RelationStructure { required RelationType type = 1; // The relationship the other person has to this person. optional RelationSubtype subtype = 2; // Any subtype the relationships may have. optional UUIDValue personId = 3; // Doesn't make much sense to be optional, but seems okay. repeated AttributeStructure attributes = 9; // Attributes specific to this relation. optional InfoStructure info = 10; // Information specific to this relation. } //======== PERSONS ================================================================================= // Types of person name. //-------------------------------------------------------------------------------------------------- enum NameType { BirthName = 1; Married = 2; Nick = 3; Professional = 4; Alias = 5; Alternate = 6; } // Name structure used for person names. Only used for name attributes in person records. //-------------------------------------------------------------------------------------------------- message NameStructure { optional NameType type = 1; // Name type -- if absent assume birth name. optional string surname = 2; // Surname string -- may contain spaces. repeated string givens = 3; // Array of given names, not including the surname. required int32 surnameIndex = 4; // Location in givens array where the surname appears. optional string prefix = 5; // Prefix for the name. optional string suffix = 6; // Suffix for the name. optional string original = 7; // Original form of the name. repeated AttributeStructure attributes = 9; // Attributes of the name. optional InfoStructure info = 10; // Optional information about this name. } // Gender values. Only used for gender attributes in person records. //-------------------------------------------------------------------------------------------------- enum GenderValue { Male = 0; Female = 1; UnknownGender = 2; } // Person record. //-------------------------------------------------------------------------------------------------- message PersonMessage { optional UUIDValue recordId = 1; // Record id of this person. repeated NameStructure names = 2; // Names of this person. required GenderValue sex = 3; // Gender of this person. repeated EventStructure vitals = 4; // Event structures of this person. repeated UUIDValue eventIds = 5; // Event records of this person. repeated RelationStructure relations = 6; // Relationships this person has to other persons. repeated UUIDValue personIds = 7; // References to sub-persons this person is based on. repeated AttributeStructure attributes = 9; // Attributes of the person. optional InfoStructure info = 10; // Optional information about this person. } //====================================== FAMILY ==================================================== // Family record. Will this stand the test of time? //-------------------------------------------------------------------------------------------------- message FamilyMessage { required UUIDValue recordId = 1; // Record id of this family. repeated UUIDValue fatherId = 2; // Father ids of this family. repeated UUIDValue motherId = 3; // Mohter ids of this family. repeated UUIDValue childIds = 4; // Child ids of this family. repeated UUIDValue eventIds = 5; // Event ids of this family. repeated AttributeStructure attributes = 9; // Attributes of this family. optional InfoStructure info = 10; // Optional information about this family. } //============================================= EVENT ============================================== // Type of event. //-------------------------------------------------------------------------------------------------- enum EventType { Birth = 1; Death = 2; Burial = 3; Marriage = 4; Divorce = 5; Arrival = 6; Residence = 7; Naturalization = 8; Other = 100; // ... Many more ... } // Role structures are only found in event structures and event records. They refer to the records // of the persons who played roles in the event. Each role has a type and optional subtype that // specifies the type. Each role must also refer to a person record. A role may also have any // number of attributes which allow the specification of any attributes of the person that are // valid only in the context of the role (e.g., age). //-------------------------------------------------------------------------------------------------- message RoleStructure { required RelationType type = 1; // Type of this role. optional RelationSubtype subtype = 2; // Subtype of this role. required UUIDValue personId = 3; // Person this role applies to. repeated AttributeStructure attributes = 9; // Attributes of the role player wrt the event. optional InfoStructure info = 10; // Optional information about this role. }; // An event structure is an event attribute in a person record. If roles are used then it might be // better to promote the event structure into a full event record. The person that contains the // event structure is the primary role player in the event. If there are any roles in the event // structure these are to other role players. //-------------------------------------------------------------------------------------------------- message EventStructure { required EventType type = 2; // Type of the event. optional string description = 3; // Description of this event. repeated DateStructure dates = 4; // Dates when this event occurred. repeated PlaceStructure places = 5; // Places where this event occurred as structures. repeated UUIDValue placeIds = 6; // Places where this event occurred as records. repeated RoleStructure roles = 7; // Roles of persons involved in the event. repeated AttributeStructure attributes = 9; // Attributes of this event. optional InfoStructure info = 10; // Optional information about this event. }; // An event record is a record whose only content is an event structure. //-------------------------------------------------------------------------------------------------- message EventMessage { required UUIDValue recordId = 1; // Record id of this event. required EventStructure event = 2; // Structure describing this event. };