RE: [Proposal]: New schema for Invoices

Added the account idea as https://github.com/schemaorg/schemaorg/issues/303 for further discussion.

From: Tom Marsh
Sent: Thursday, January 29, 2015 10:02 AM
To: 'Vicki Tardif Holland'
Cc: 'Martin Hepp'; 'W3C Web Schemas Task Force'
Subject: RE: [Proposal]: New schema for Invoices

Ignore my last question. Just saw it’s on sdo-stantz.

From: Tom Marsh
Sent: Thursday, January 29, 2015 10:01 AM
To: 'Vicki Tardif Holland'
Cc: Martin Hepp; W3C Web Schemas Task Force
Subject: RE: [Proposal]: New schema for Invoices

OK, I am convinced that Order and Invoice are separate. I think one more example would be helpful to illustrate this: a lawyer or architect offering services where the “order” is for those services, but invoices are sent as individual units of work are completed (generally, hours spent + material costs) that were not precisely “ordered”. I think this might be clearer than the water heater example (which I think is still good to keep) because the consumer didn’t order the specific things being invoiced.

When an order has orderStatus == OrderPaymentDue, it seems like we should have a link (new property on Order, inverse of referencesOrder) to the invoice requesting payment. Thoughts?

In the examples, it would be helpful to also show where I can see the full invoice (usually a PDF or something like that), in case the markup is presented on a summary. I would expect to just use the url property for that.

The water bill and Visa bill examples are still throwing me a bit. I feel that there ought to be somewhere to represent the original agreement between the consumer and the service provider and that the invoice should refer back to that thing. Without this, the invoice doesn’t adequately describe why payment is due. Do you agree? If so, how would you represent the original agreement? Maybe we need an Account type, or more specifically a ServiceAccount type? Something that would represent the current balance, transaction history (water usage in the water bill case, purchases, interest, and fees in the Visa case). Maybe we could include this type in a future iteration?

Finally, is this change hosted somewhere yet?


From: Vicki Tardif Holland [mailto:vtardif@google.com]
Sent: Thursday, January 22, 2015 1:07 PM
To: Tom Marsh
Cc: Martin Hepp; W3C Web Schemas Task Force
Subject: Re: [Proposal]: New schema for Invoices

I'm finally getting around to this.

I think Invoice is different than Order in that I may receive an invoice that is not really attached to an Order. For example, a utility bill is not really attached to an order, so much as an ongoing account.

To address some of the comments, I have updated the schema at https://github.com/vholland/schemaorg/blob/sdo-bills/data/schema.rdfa. Specifically, I

- Added Invoice to the domain for paymentMethod to coordinate with Order.
- Removed payFromAccountId in favor of the existing paymentMethodId.
- Added a property referencesOrder to link an Invoice to one or more Orders if applicable.

I wrote up some examples at https://github.com/vholland/schemaorg/blob/sdo-bills/data/sdo-invoice-examples.txt (using your furnace suggestion).

In the example, I have allowed for an Order to refer to a service. If people object to that, I can take it out. Currently, one can only Order/Offer something of type Product.

- Vicki

Vicki Tardif Holland | Ontologist | vtardif@google.com<mailto:vtardif@google.com>


On Mon, Dec 22, 2014 at 1:28 PM, Tom Marsh <tmarsh@exchange.microsoft.com<mailto:tmarsh@exchange.microsoft.com>> wrote:


From: Vicki Tardif Holland [mailto:vtardif@google.com<mailto:vtardif@google.com>]
Sent: Monday, December 22, 2014 8:47 AM
To: Tom Marsh
Cc: Martin Hepp; W3C Web Schemas Task Force
Subject: Re: [Proposal]: New schema for Invoices


On Sun, Dec 21, 2014 at 1:02 PM, Tom Marsh <tmarsh@exchange.microsoft.com<mailto:tmarsh@exchange.microsoft.com>> wrote:
What is the difference between Order and Invoice? With the use of orderStatus == OrderPaymentDue (or lack thereof for paid invoices/orders), it looks like I can specify the same things that I can with Invoice. How would a publisher know when to use one vs. the other?

The Invoice type is intended for cases where there is no original purchase from the entity owed money. For example, credit card or utility bills do not have a single purchase associated with the debt. I am fine with rolling this type into the existing Order, but it should be simple to say "this is a water bill for December" or "American Express is billing me for November".

After the new year, I will send along some examples.

[Tom] Agreed on the use cases. I was expecting those to be modeled as orders for services, which is why I suggested we might want to extend the range of orderedItem to include Service. Assuming that we added Service to the range, separated out paymentStatus, and made Invoice inherit from Order with just the addition of the billingPeriod property, for the water bill example, you would end up with something like:
1) A Service (+ offer) to describe the water service, the service location, etc.
2) An Invoice that used the totalPaymentDue, minimumPaymentDue, accountId, etc. properties from Order to describe how much was due and when. The billingPeriod from Invoice would specify that it was December that was covered by the bill/invoice.

As another example, let’s say that I buy a new furnace where there is a down payment before installation and then a final payment after installation. Then you would have something like:
1) A Product (+ offer) to describe the furnace
2) A Service (+ offer) to describe the installation (assuming the contractor separates out labor & materials)
3) Two orders (or, if you prefer, two versions of the same order): one to describe the down payment and one to describe the final payment. I would expect both orders to have almost identical properties, differing only in totalPaymentDue, paymentDue, and description (which would likely be the only way to describe that one was a deposit and the other was a final payment). The order(s) could equally well be Invoices, but since there is no billing period, the types are synonymous in this scenario.


BTW, you have a typo on the label of some of the ranges (e.g., for totalPaymentDue), which are labeled as “Domain: “ instead of “Range: “

Thanks for the heads up. I'll clean these up.

- Vicki

Vicki Tardif Holland | Ontologist | vtardif@google.com<mailto:vtardif@google.com>