api/party/model.proto (309 lines of code) (raw):

/** * Copyright 2022 Google LLC * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ syntax = "proto3"; package google.retail.party.pb; // Go Lang Options option go_package = "github.com/GoogleCloudPlatform/retail-data-model/party/pb"; // Java Options option java_package = "com.google.retail.party.pb"; option java_multiple_files = true; import "google/protobuf/timestamp.proto"; import "api/common/model.proto"; import "api/enums/currency.proto"; import "api/enums/party.proto"; import "api/enums/lang.proto"; message PartyTemplate { enum Type { PERSON = 0; ORGANIZATION = 1; HOUSEHOLD = 2; COMMUNITY = 3; } message Field { bool required = 1; bool repeatable = 2; string validation_regex = 3; string name = 4; string description = 5; } string id = 1; int32 version = 2; Type party_type_id = 3; string name = 4; string description = 5; repeated Field fields = 6; } message FieldValue { } /* * A person or organization that exchanges information, * tender and/or goods and *services with a retailer. */ message Party { google.retail.common.pb.VersionID id = 1; string party_template_id = 2; int32 path_template_version = 3; } /* * Represents the effective state of a party. It's a best practice to keep a * history of party registration events hence the effective and expiration * dates. */ message PartyRegistrationState { enum Registration { UNKNOWN_CONSUMER = 0; REGISTERED_NOT_VALIDATED = 1; REGISTERED_VALIDATED = 2; UNREGISTERED = 3; } google.retail.common.pb.VersionID id = 1; google.retail.common.pb.VersionID party_id = 2; Registration registration = 3; google.protobuf.Timestamp effective_date = 4; google.protobuf.Timestamp expiration_date = 5; bool do_not_call = 6; bool do_not_email = 7; bool do_not_share = 8; bool do_not_track = 9; } /* * PartyRole identifies, names and describes different parts a Party may play * when interacting with a retailer. PartyRole is an important concept because * is enables one person or organization to play multiple parts (e.g. a worker * who is also a customer) without having to replicate name, address and other * contract data. * * Example: Consumer, Veteran, Worker, Vendor, Supplier, Tax Authority * * For more explicitly modeled PartyRole type see Logical 06310 Party-Role VIew * subject area). */ message PartyRole { google.retail.common.pb.VersionID id = 1; } /* * A description for a party identification type such as a drivers license */ message PartyIdentityDefinition { google.retail.common.pb.VersionID id = 1; /* * A set of retailer specific keys such as 'state', 'country' * used to narrow applicability. */ map<string, string> key_set = 2; /* * Field level definitions such as "Name":"The name on the ID". */ map<string, string> meta_definitions = 3; /* * The Field name plus a validation expression such as "Name","\w+ \w+" */ map<string, string> meta_validations = 4; } /* * An official number that may be used to identify a Party. People have multiple * forms of such identification: Drivers License number , Passport number, * Insurance group and policy numbers, etc. * * Note that PartyIdentification could also apply to social security number, * credit/debit accounts but these SHOULD never be retained by a retailer except * where explicitly permitted for tax or regulatory purposes. * */ message PartyIdentification { string party_id = 1; string party_identification_definition_name = 2; int32 party_identification_definition_version = 3; map<string, string> values = 4; } /* * Temporal record of when the Party became (and ceased to be) related to the * Retail Enterprise via the PartyRole. * * This entity represents the different varieties of relationships that may * exist between the retailer and other organizations and individuals (parties) * through time (hence the effective and expiration dates). */ message PartyRoleAssignment { string party_id = 1; string party_role_type_id = 2; /* * A retailer assigned code denoting the current status of the * PartyRoleAssignment. */ string status_code = 3; /* * A code that identifies a group of PARTY ROLES. This is used for subtyping * the PARTY ROLEs. */ google.protobuf.Timestamp effective_date = 4; google.protobuf.Timestamp expiration_date = 5; } /* * A separate legal entity which conducts retail operations on behalf of the * retail enterprise in some geographical location. */ message OperationalParty { string id = 1; string party_role_assignment_id = 2; } /* * A record for tracking legal entity operations through time and changes */ message EffectiveParty { string party_id = 1; google.protobuf.Timestamp effective_date = 2; google.protobuf.Timestamp expiration_date = 3; } /* * A Household is an identifiable, named, defined group of Person party subtypes * that make retail related decisions together. Traditionally households are * tied to residential addresses and represented nuclear families. Today these * qualifiers of household don't always apply so it is a more generic way to * gather individual parties into a economic decision making unit. * * Households share some characteristics with Organization and Community - but * they are important to retailers because they represent groups of parties that * purchase and consume products and services as an economic decision making * unit. In ARTS we are distinguishing Households from Organizations (which are * more typically representing commercial, public of charitable business * establishments) and communities which may or may not have clearly delineated * economic decision making capacity. */ message Household { EffectiveParty id = 1; string name = 2; google.retail.enums.currency.Currency primary_currency = 3; double household_income = 4; reserved 5 to 99; map<string, string> additional_dimensions = 100; } /* * A sub-type of party that represents an individual of interest to the retail * store or retail enterprise. */ message Person { EffectiveParty id = 1; string language_id = 2; string title = 3; string first_name = 4; // A code denoting what kind of name the FirstName is, possible values // include: GivenName, OtherGivenName, FamilyName, Patronymic string first_name_type = 5; string middle_name = 6; string middle_name_type = 7; string last_name = 8; string last_name_type = 9; string suffix = 10; string sorting_name = 11; string mailing_name = 12; string official_name = 13; reserved 14 to 29; google.retail.enums.party.Gender gender = 30; google.retail.enums.party.Pronoun pronoun = 31; google.retail.enums.party.MaritalStatus marital_status = 32; google.retail.enums.party.LifeStage life_stage = 33; google.retail.enums.party.Race race = 34; google.retail.enums.party.Ethnicity ethnicity = 35; google.retail.enums.party.ReligionGroup religion_group = 36; google.retail.enums.party.Religion religion = 37; google.retail.enums.party.EmploymentStatus employment_status = 38; google.retail.enums.party.Occupation occupation = 39; google.retail.enums.currency.Currency primary_currency = 40; reserved 41 to 99; string annual_income_range = 100; string disability_impairment_type = 101; string personality_type = 102; string lifestyle_type = 103; string personal_value_type = 104; string value_attitude_lifestyle_type = 105; string dietary_habit_type = 106; string consumer_credit_score = 107; string consumer_credit_rating_service_name = 108; reserved 109 to 199; map<string, string> additional_dimensions = 200; } /* * A company, association, institution, or other enterprise of interest to a * retail store or retail enterprise. * * Note that because this is a RETAIL view of customer organizations is is more * limited than a wholesale or manufacturing view of trading partner. This * treatment of Organization is not and should not be used as a substitute for * B2B trading partner information. */ message Organization { EffectiveParty id = 1; string legal_name = 2; string trade_name = 3; string business_activity = 4; google.retail.enums.party.BusinessClassification business_classification = 5; string jurisdiction = 6; google.protobuf.Timestamp open_for_business = 7; google.protobuf.Timestamp closed_for_business = 8; google.protobuf.Timestamp incorporation_date = 9; google.protobuf.Timestamp fiscal_year_end_date = 10; google.retail.enums.lang.Language primary_language = 11; repeated google.retail.enums.lang.Language supported_languages = 12; google.retail.enums.currency.Currency primary_currency = 13; double local_annual_revenue_amount = 14; double global_annual_revenue_amount = 15; int32 local_employee_count = 16; int32 global_employee_count = 17; reserved 18 to 49; google.retail.enums.party.ReligionGroup religion_group = 50; google.retail.enums.party.Religion religion = 51; reserved 52 to 99; bool bankruptcy = 100; bool duns_information = 101; reserved 102 to 199; map<string, string> additional_dimensions = 200; } /* * The D&B DUNS Number is a non-indicative, nine-digit number assigned to each * business location in the D&B database having a unique, separate, and distinct * operation, and is maintained solely by D&B. The D&B DUNS Number is used by * industries and organizations around the world as a global standard for * business identification and tracking. If you don`t have a D-U-N-S Number, * you can get one for free through the SBS site. */ message OrganizationDUNSInformation { EffectiveParty id = 1; string duns_number = 2; string duns_rating = 3; } /* * Historic perspective of an organizations statuses of bankruptcy reputation. */ message OrganizationBankruptcy { EffectiveParty id = 1; google.protobuf.Timestamp date = 2; google.protobuf.Timestamp emergence_date = 3; google.retail.enums.party.Bankruptcy bankruptcy = 4; string additional_information = 5; } /* * Community represents a group of parties associated to a formal community */ message Community { EffectiveParty id = 1; string Name = 2; google.retail.enums.currency.Currency primary_currency = 3; reserved 4 to 99; map<string, string> additional_dimensions = 100; }